aside-apple-passwords

name	aside-apple-passwords
description	Use Apple Passwords on macOS when the user asks for Apple/iCloud passwords, OTPs, or autofill from Apple's Passwords app.
metadata	{"version":"0.1.0"}

Apple Passwords

Use the applePasswords global in the REPL to read or autofill credentials from Apple's Passwords app on macOS.

Critical Touch ID Rule

Before calling getPasswords, getOtps, or autofillLogin, notify the user first with the notification tool. These calls can trigger a macOS Touch ID / Apple Passwords auth prompt and will not return until the user approves or cancels it.

Never ask the user to reveal a password, OTP seed, recovery code, or Touch ID result. Prefer autofillLogin when signing in because it fills the secret without printing it.

Quick Reference

// Check helper availability.
console.log(await applePasswords.capabilities());

// First-time auth, only when a call says Apple Passwords is not authenticated.
await applePasswords.requestAuth();
// Ask the user for the 6-digit Apple Passwords code only if macOS shows one.
await applePasswords.verifyAuth('<pin>');

// Find accounts for a site. No password is returned.
console.log(await applePasswords.listLogins('https://example.com'));
// -> [{ username, domains }]

// Notify the user before this call; it may wait on Touch ID.
const passwords = await applePasswords.getPasswords('https://example.com', '[e-mail]');
// -> [{ username, domain, password }]

// Notify the user before this call; it may wait on Touch ID.
await applePasswords.autofillLogin(page, {
  url: 'https://example.com',
  username: '[e-mail]',
  usernameField: 'e12',
  passwordField: 'e13',
  submit: true,
});
// -> { status: 'filled', username, domain, passwordFilled: true }

// Notify the user before this call; it may wait on Touch ID.
console.log(await applePasswords.getOtps('https://example.com'));
// -> [{ username, domain, code, source }]

Method Contract

declare global {
  const applePasswords: ApplePasswordsApi;
}

interface ApplePasswordsApi {
  capabilities(): Promise<Record<string, unknown>>;
  requestAuth(): Promise<{ status: 'auth-requested'; instruction: string }>;
  verifyAuth(pin: string): Promise<{ status: 'authenticated' }>;
  listLogins(url: string): Promise<Array<{ username: string; domains: string[] }>>;
  getPasswords(url: string, username?: string): Promise<Array<{ username: string; domain: string; password: string }>>;
  getOtps(url: string): Promise<Array<{ username: string; : ; : ; ?:  }>>;
  (: , ?: {
    ?: ; 
    ?: ; 
    ?: ; 
    ?: ; 
    ?: ; 
  }): <{ : ; : ; : ; :  }>;
}

Selection Rules

• Use listLogins(url) first when account choice is unclear.
• If multiple logins match, choose by visible site/account context; ask the user only when genuinely ambiguous.
• Do not print passwords unless the user explicitly asked to retrieve/show the password. For login tasks, call autofillLogin.
• If autofillLogin cannot find fields automatically, take a fresh snapshot() and pass usernameField / passwordField refs.