unotoken 0.1.0

package/dist/oauth/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * OAuth module for unotoken.
+ *
+ * Provides a provider-agnostic PKCE browser flow engine
+ * for authenticating users via OAuth/OIDC providers,
+ * plus key wrapping for OAuth-derived vault unlock.
+ */
+export { generatePKCE, computeChallenge, type PKCEPair } from './pkce.js';
+export type { OAuthProvider, OAuthIdentity, TokenResponse, } from './provider.js';
+export { runOAuthFlow, startCallbackServer, openSystemBrowser, exchangeCode, OAuthTimeoutError, OAuthCallbackError, OAuthTokenError, type OAuthFlowConfig, type OAuthFlowResult, } from './flow.js';
+export { wrapMasterKey, unwrapMasterKey, listOAuthLinks, removeOAuthLink, initOAuthLinksTable, deriveWrapKey, encryptMasterKey, decryptMasterKey, KeyUnwrapError, WRAP_KEY_BYTES, WRAP_SALT_BYTES, WRAP_NONCE_BYTES, type OAuthLinkRow, type OAuthLinksDb, } from './key-wrap.js';
+export { generateDeviceSecret, readDeviceSecret, deviceSecretExists, getDeviceKeyPath, getDeviceDir, DeviceSecretMissingError, DEVICE_SECRET_BYTES, } from './device-secret.js';
+export { createGoogleProvider, clearGoogleCaches, type GoogleProviderOptions, type GoogleDiscoveryDocument, type GoogleIdTokenClaims, type JWK, type JWKSResponse, } from './providers/google.js';
+export { createGitHubProvider, type GitHubProviderOptions, type GitHubUser, } from './providers/github.js';
+export { deriveMasterKey, decryptWithKey, verifyMasterKey, SALT_BYTES, KEY_BYTES, NONCE_BYTES, } from './crypto-helpers.js';
+export { authLink, unlockWithOAuth, listLinkedProviders, unlinkProvider, isValidProvider, resolveProvider, MultipleProvidersError, type ProviderName, type AuthLinkOptions, type AuthLinkResult, type UnlockOAuthOptions, type UnlockOAuthResult, type UnlinkResult, type LinkedProvider, } from './commands.js';
+export { loadOAuthConfig, saveOAuthConfig, resetOAuthConfig, updateOAuthConfig, hasCustomConfig, formatConfigForDisplay, maskSecret, getConfigPath, type OAuthConfigFile, } from './config.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/oauth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/oauth/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE1E,YAAY,EACV,aAAa,EACb,aAAa,EACb,aAAa,GACd,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,eAAe,GACrB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,aAAa,EACb,eAAe,EACf,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,KAAK,YAAY,EACjB,KAAK,YAAY,GAClB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,YAAY,EACZ,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,GAAG,EACR,KAAK,YAAY,GAClB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,oBAAoB,EACpB,KAAK,qBAAqB,EAC1B,KAAK,UAAU,GAChB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,eAAe,EACf,cAAc,EACd,eAAe,EACf,UAAU,EACV,SAAS,EACT,WAAW,GACZ,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,QAAQ,EACR,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,eAAe,EACf,eAAe,EACf,sBAAsB,EACtB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,cAAc,GACpB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,sBAAsB,EACtB,UAAU,EACV,aAAa,EACb,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC"}

package/dist/oauth/index.js

@@ -0,0 +1,24 @@
+/**
+ * OAuth module for unotoken.
+ *
+ * Provides a provider-agnostic PKCE browser flow engine
+ * for authenticating users via OAuth/OIDC providers,
+ * plus key wrapping for OAuth-derived vault unlock.
+ */
+export { generatePKCE, computeChallenge } from './pkce.js';
+export { runOAuthFlow, startCallbackServer, openSystemBrowser, exchangeCode, OAuthTimeoutError, OAuthCallbackError, OAuthTokenError, } from './flow.js';
+// Key wrapping for OAuth-derived unlock (US-003)
+export { wrapMasterKey, unwrapMasterKey, listOAuthLinks, removeOAuthLink, initOAuthLinksTable, deriveWrapKey, encryptMasterKey, decryptMasterKey, KeyUnwrapError, WRAP_KEY_BYTES, WRAP_SALT_BYTES, WRAP_NONCE_BYTES, } from './key-wrap.js';
+// Device secret management (US-003)
+export { generateDeviceSecret, readDeviceSecret, deviceSecretExists, getDeviceKeyPath, getDeviceDir, DeviceSecretMissingError, DEVICE_SECRET_BYTES, } from './device-secret.js';
+// Google OIDC provider (US-004)
+export { createGoogleProvider, clearGoogleCaches, } from './providers/google.js';
+// GitHub OAuth provider (US-005)
+export { createGitHubProvider, } from './providers/github.js';
+// Crypto helpers for vault operations (US-006)
+export { deriveMasterKey, decryptWithKey, verifyMasterKey, SALT_BYTES, KEY_BYTES, NONCE_BYTES, } from './crypto-helpers.js';
+// OAuth CLI commands (US-006 + US-007)
+export { authLink, unlockWithOAuth, listLinkedProviders, unlinkProvider, isValidProvider, resolveProvider, MultipleProvidersError, } from './commands.js';
+// OAuth config management (US-007)
+export { loadOAuthConfig, saveOAuthConfig, resetOAuthConfig, updateOAuthConfig, hasCustomConfig, formatConfigForDisplay, maskSecret, getConfigPath, } from './config.js';
+//# sourceMappingURL=index.js.map

package/dist/oauth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/oauth/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAiB,MAAM,WAAW,CAAC;AAQ1E,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,GAGhB,MAAM,WAAW,CAAC;AAEnB,iDAAiD;AACjD,OAAO,EACL,aAAa,EACb,eAAe,EACf,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,eAAe,EACf,gBAAgB,GAGjB,MAAM,eAAe,CAAC;AAEvB,oCAAoC;AACpC,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,YAAY,EACZ,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAE5B,gCAAgC;AAChC,OAAO,EACL,oBAAoB,EACpB,iBAAiB,GAMlB,MAAM,uBAAuB,CAAC;AAE/B,iCAAiC;AACjC,OAAO,EACL,oBAAoB,GAGrB,MAAM,uBAAuB,CAAC;AAE/B,+CAA+C;AAC/C,OAAO,EACL,eAAe,EACf,cAAc,EACd,eAAe,EACf,UAAU,EACV,SAAS,EACT,WAAW,GACZ,MAAM,qBAAqB,CAAC;AAE7B,uCAAuC;AACvC,OAAO,EACL,QAAQ,EACR,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,eAAe,EACf,eAAe,EACf,sBAAsB,GAQvB,MAAM,eAAe,CAAC;AAEvB,mCAAmC;AACnC,OAAO,EACL,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,sBAAsB,EACtB,UAAU,EACV,aAAa,GAEd,MAAM,aAAa,CAAC"}

package/dist/oauth/key-wrap.d.ts

@@ -0,0 +1,146 @@
+/**
+ * OAuth key wrapping — encrypt/decrypt the vault master key using an
+ * OAuth-derived wrap key.
+ *
+ * Flow:
+ * 1. User authenticates via OAuth (gets provider + subject_id)
+ * 2. Wrap key = HKDF-SHA256(ikm=device_secret, salt=random, info=provider+subject_id)
+ * 3. Wrapped key = XChaCha20-Poly1305(plaintext=master_key, key=wrap_key)
+ * 4. Stored in SQLite oauth_links table alongside salt and nonce
+ *
+ * Unwrap flow:
+ * 1. User authenticates via OAuth (gets provider + subject_id)
+ * 2. Look up row in oauth_links
+ * 3. Re-derive wrap key from device_secret + stored salt
+ * 4. Decrypt wrapped_key → master_key
+ *
+ * @module
+ */
+/** Key/nonce/salt sizes */
+export declare const WRAP_KEY_BYTES = 32;
+export declare const WRAP_SALT_BYTES = 32;
+export declare const WRAP_NONCE_BYTES = 24;
+/**
+ * Row shape for the oauth_links SQLite table.
+ */
+export interface OAuthLinkRow {
+    provider: string;
+    subject_id: string;
+    wrap_salt: Buffer;
+    wrapped_key: Buffer;
+    nonce: Buffer;
+    created_at: string;
+    last_used_at: string;
+}
+/**
+ * Minimal database interface for oauth_links table operations.
+ *
+ * This abstraction allows the key-wrap module to work with any sql.js
+ * database instance (typically obtained via VaultEngine.getDb().getRawDb()).
+ *
+ * sql.js Database objects expose: run(), exec(), prepare().
+ * Parameterized queries use prepare() → bind() → step() → getAsObject() → free().
+ */
+export interface OAuthLinksDb {
+    run(sql: string, params?: unknown[]): void;
+    exec(sql: string): void;
+    prepare(sql: string): {
+        bind(params?: unknown[]): boolean;
+        step(): boolean;
+        getAsObject(): Record<string, unknown>;
+        free(): void;
+    };
+}
+/**
+ * Initialize the oauth_links table if it does not exist.
+ *
+ * Called once when the key-wrap module is first used against a database.
+ */
+export declare function initOAuthLinksTable(db: OAuthLinksDb): void;
+/**
+ * Derive a 32-byte wrap key using HKDF-SHA256.
+ *
+ * @param deviceSecret - 32-byte device secret (IKM)
+ * @param wrapSalt - 32-byte random salt (unique per link)
+ * @param provider - OAuth provider name (e.g., 'google')
+ * @param subjectId - Provider-specific user ID
+ * @returns 32-byte wrap key
+ */
+export declare function deriveWrapKey(deviceSecret: Buffer, wrapSalt: Buffer, provider: string, subjectId: string): Buffer;
+/**
+ * Wrap (encrypt) the master key with an OAuth-derived wrap key.
+ *
+ * Uses XChaCha20-Poly1305 for authenticated encryption.
+ *
+ * @param masterKey - The vault master key to wrap (32 bytes)
+ * @param wrapKey - The HKDF-derived wrap key (32 bytes)
+ * @returns Object containing wrapped (encrypted) key and the nonce used
+ */
+export declare function encryptMasterKey(masterKey: Buffer, wrapKey: Buffer): Promise<{
+    wrappedKey: Buffer;
+    nonce: Buffer;
+}>;
+/**
+ * Unwrap (decrypt) the master key with an OAuth-derived wrap key.
+ *
+ * Uses XChaCha20-Poly1305 for authenticated decryption.
+ *
+ * @param wrappedKey - The encrypted master key
+ * @param nonce - The nonce used during encryption
+ * @param wrapKey - The HKDF-derived wrap key (32 bytes)
+ * @returns The decrypted master key (32 bytes)
+ * @throws Error if the wrap key is wrong or data is corrupted
+ */
+export declare function decryptMasterKey(wrappedKey: Buffer, nonce: Buffer, wrapKey: Buffer): Promise<Buffer>;
+/**
+ * Error thrown when key unwrapping fails.
+ */
+export declare class KeyUnwrapError extends Error {
+    constructor(message: string);
+}
+/**
+ * Wrap the master key for an OAuth identity and store in the database.
+ *
+ * This is the main entry point for linking an OAuth identity.
+ * Called after the user authenticates via OAuth while the vault is unlocked.
+ *
+ * @param db - sql.js database instance (from VaultEngine.getDb().getRawDb())
+ * @param masterKey - The current vault master key (32 bytes)
+ * @param provider - OAuth provider name (e.g., 'google', 'github')
+ * @param subjectId - Provider-specific unique user ID
+ * @param deviceDir - Optional directory for device.key (default: ~/.yokotoken)
+ */
+export declare function wrapMasterKey(db: OAuthLinksDb, masterKey: Buffer, provider: string, subjectId: string, deviceDir?: string): Promise<void>;
+/**
+ * Unwrap the master key using an OAuth identity.
+ *
+ * This is the main entry point for OAuth-based vault unlock.
+ * Called after the user authenticates via OAuth.
+ *
+ * @param db - sql.js database instance (from VaultEngine.getDb().getRawDb())
+ * @param provider - OAuth provider name (e.g., 'google', 'github')
+ * @param subjectId - Provider-specific unique user ID
+ * @param deviceDir - Optional directory for device.key (default: ~/.yokotoken)
+ * @returns The decrypted vault master key (32 bytes)
+ * @throws KeyUnwrapError if decryption fails (wrong identity)
+ * @throws DeviceSecretMissingError if device.key is not found
+ * @throws Error if no link exists for the given provider+subject_id
+ */
+export declare function unwrapMasterKey(db: OAuthLinksDb, provider: string, subjectId: string, deviceDir?: string): Promise<Buffer>;
+/**
+ * List all linked OAuth providers for the current vault.
+ *
+ * @param db - sql.js database instance
+ * @returns Array of link rows (provider, subject_id, created_at, last_used_at)
+ */
+export declare function listOAuthLinks(db: OAuthLinksDb): OAuthLinkRow[];
+/**
+ * Remove an OAuth link for a provider.
+ *
+ * @param db - sql.js database instance
+ * @param provider - OAuth provider name
+ * @param subjectId - Optional subject ID (if omitted, removes all links for the provider)
+ * @returns true if a row was deleted
+ */
+export declare function removeOAuthLink(db: OAuthLinksDb, provider: string, subjectId?: string): boolean;
+//# sourceMappingURL=key-wrap.d.ts.map

package/dist/oauth/key-wrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-wrap.d.ts","sourceRoot":"","sources":["../../src/oauth/key-wrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AASH,2BAA2B;AAC3B,eAAO,MAAM,cAAc,KAAK,CAAC;AACjC,eAAO,MAAM,eAAe,KAAK,CAAC;AAClC,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAWnC;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC3C,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG;QACpB,IAAI,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAClC,IAAI,IAAI,OAAO,CAAC;QAChB,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACvC,IAAI,IAAI,IAAI,CAAC;KACd,CAAC;CACH;AAiBD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAa1D;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,MAAM,CAaR;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAiBhD;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CAqBjB;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAID;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,EAAE,EAAE,YAAY,EAChB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAiCf;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CACnC,EAAE,EAAE,YAAY,EAChB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAgDjB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,YAAY,GAAG,YAAY,EAAE,CAwB/D;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,YAAY,EAChB,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAyBT"}

package/dist/oauth/key-wrap.js

@@ -0,0 +1,275 @@
+/**
+ * OAuth key wrapping — encrypt/decrypt the vault master key using an
+ * OAuth-derived wrap key.
+ *
+ * Flow:
+ * 1. User authenticates via OAuth (gets provider + subject_id)
+ * 2. Wrap key = HKDF-SHA256(ikm=device_secret, salt=random, info=provider+subject_id)
+ * 3. Wrapped key = XChaCha20-Poly1305(plaintext=master_key, key=wrap_key)
+ * 4. Stored in SQLite oauth_links table alongside salt and nonce
+ *
+ * Unwrap flow:
+ * 1. User authenticates via OAuth (gets provider + subject_id)
+ * 2. Look up row in oauth_links
+ * 3. Re-derive wrap key from device_secret + stored salt
+ * 4. Decrypt wrapped_key → master_key
+ *
+ * @module
+ */
+import { hkdfSync, randomBytes } from 'node:crypto';
+import { readDeviceSecret, generateDeviceSecret } from './device-secret.js';
+// Libsodium is loaded via yokotoken's transitive dependency.
+// We import it the same way yokotoken's crypto module does.
+import sodium from 'libsodium-wrappers-sumo';
+/** Key/nonce/salt sizes */
+export const WRAP_KEY_BYTES = 32;
+export const WRAP_SALT_BYTES = 32;
+export const WRAP_NONCE_BYTES = 24; // XChaCha20-Poly1305
+/** Ensure libsodium WASM is initialized. */
+let sodiumReady = false;
+async function ensureSodium() {
+    if (!sodiumReady) {
+        await sodium.ready;
+        sodiumReady = true;
+    }
+}
+/**
+ * Execute a parameterized query and return a single row as an object.
+ * Returns an empty object if no rows match.
+ */
+function queryOne(db, sql, params) {
+    const stmt = db.prepare(sql);
+    stmt.bind(params);
+    let result = {};
+    if (stmt.step()) {
+        result = stmt.getAsObject();
+    }
+    stmt.free();
+    return result;
+}
+/**
+ * Initialize the oauth_links table if it does not exist.
+ *
+ * Called once when the key-wrap module is first used against a database.
+ */
+export function initOAuthLinksTable(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS oauth_links (
+      provider    TEXT NOT NULL,
+      subject_id  TEXT NOT NULL,
+      wrap_salt   BLOB NOT NULL,
+      wrapped_key BLOB NOT NULL,
+      nonce       BLOB NOT NULL,
+      created_at  TEXT NOT NULL DEFAULT (datetime('now')),
+      last_used_at TEXT NOT NULL DEFAULT (datetime('now')),
+      PRIMARY KEY (provider, subject_id)
+    )
+  `);
+}
+/**
+ * Derive a 32-byte wrap key using HKDF-SHA256.
+ *
+ * @param deviceSecret - 32-byte device secret (IKM)
+ * @param wrapSalt - 32-byte random salt (unique per link)
+ * @param provider - OAuth provider name (e.g., 'google')
+ * @param subjectId - Provider-specific user ID
+ * @returns 32-byte wrap key
+ */
+export function deriveWrapKey(deviceSecret, wrapSalt, provider, subjectId) {
+    // info = "unotoken-oauth:" + provider + ":" + subjectId
+    const info = `unotoken-oauth:${provider}:${subjectId}`;
+    const key = hkdfSync('sha256', deviceSecret, // IKM (input keying material)
+    wrapSalt, // salt
+    info, // info/context string
+    WRAP_KEY_BYTES);
+    return Buffer.from(key);
+}
+/**
+ * Wrap (encrypt) the master key with an OAuth-derived wrap key.
+ *
+ * Uses XChaCha20-Poly1305 for authenticated encryption.
+ *
+ * @param masterKey - The vault master key to wrap (32 bytes)
+ * @param wrapKey - The HKDF-derived wrap key (32 bytes)
+ * @returns Object containing wrapped (encrypted) key and the nonce used
+ */
+export async function encryptMasterKey(masterKey, wrapKey) {
+    await ensureSodium();
+    const nonce = sodium.randombytes_buf(WRAP_NONCE_BYTES);
+    const ciphertext = sodium.crypto_aead_xchacha20poly1305_ietf_encrypt(new Uint8Array(masterKey), null, // no additional data
+    null, // nsec (unused, always null)
+    nonce, new Uint8Array(wrapKey));
+    return {
+        wrappedKey: Buffer.from(ciphertext),
+        nonce: Buffer.from(nonce),
+    };
+}
+/**
+ * Unwrap (decrypt) the master key with an OAuth-derived wrap key.
+ *
+ * Uses XChaCha20-Poly1305 for authenticated decryption.
+ *
+ * @param wrappedKey - The encrypted master key
+ * @param nonce - The nonce used during encryption
+ * @param wrapKey - The HKDF-derived wrap key (32 bytes)
+ * @returns The decrypted master key (32 bytes)
+ * @throws Error if the wrap key is wrong or data is corrupted
+ */
+export async function decryptMasterKey(wrappedKey, nonce, wrapKey) {
+    await ensureSodium();
+    try {
+        const plaintext = sodium.crypto_aead_xchacha20poly1305_ietf_decrypt(null, // nsec (unused)
+        new Uint8Array(wrappedKey), null, // no additional data
+        new Uint8Array(nonce), new Uint8Array(wrapKey));
+        return Buffer.from(plaintext);
+    }
+    catch {
+        throw new KeyUnwrapError('Failed to unwrap master key: wrong identity or corrupted data. ' +
+            'The OAuth account used may not match the one that was linked, ' +
+            'or the device.key file may have changed. ' +
+            'Use your passphrase to unlock and re-link with \'unotoken auth link <provider>\'.');
+    }
+}
+/**
+ * Error thrown when key unwrapping fails.
+ */
+export class KeyUnwrapError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'KeyUnwrapError';
+    }
+}
+// ─── High-level wrap/unwrap operations ───────────────────────────────
+/**
+ * Wrap the master key for an OAuth identity and store in the database.
+ *
+ * This is the main entry point for linking an OAuth identity.
+ * Called after the user authenticates via OAuth while the vault is unlocked.
+ *
+ * @param db - sql.js database instance (from VaultEngine.getDb().getRawDb())
+ * @param masterKey - The current vault master key (32 bytes)
+ * @param provider - OAuth provider name (e.g., 'google', 'github')
+ * @param subjectId - Provider-specific unique user ID
+ * @param deviceDir - Optional directory for device.key (default: ~/.yokotoken)
+ */
+export async function wrapMasterKey(db, masterKey, provider, subjectId, deviceDir) {
+    // Ensure table exists
+    initOAuthLinksTable(db);
+    // Generate or read device secret
+    const deviceSecret = generateDeviceSecret(deviceDir);
+    // Generate random salt for this link
+    const wrapSalt = randomBytes(WRAP_SALT_BYTES);
+    // Derive wrap key via HKDF
+    const wrapKey = deriveWrapKey(deviceSecret, wrapSalt, provider, subjectId);
+    // Encrypt master key
+    const { wrappedKey, nonce } = await encryptMasterKey(masterKey, wrapKey);
+    // Securely zero the wrap key
+    try {
+        await ensureSodium();
+        sodium.memzero(new Uint8Array(wrapKey.buffer, wrapKey.byteOffset, wrapKey.byteLength));
+    }
+    catch {
+        // Best-effort secure zeroing
+    }
+    const now = new Date().toISOString();
+    // Upsert into oauth_links (replace if provider+subject_id already linked)
+    db.run(`INSERT OR REPLACE INTO oauth_links
+       (provider, subject_id, wrap_salt, wrapped_key, nonce, created_at, last_used_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`, [provider, subjectId, wrapSalt, wrappedKey, nonce, now, now]);
+}
+/**
+ * Unwrap the master key using an OAuth identity.
+ *
+ * This is the main entry point for OAuth-based vault unlock.
+ * Called after the user authenticates via OAuth.
+ *
+ * @param db - sql.js database instance (from VaultEngine.getDb().getRawDb())
+ * @param provider - OAuth provider name (e.g., 'google', 'github')
+ * @param subjectId - Provider-specific unique user ID
+ * @param deviceDir - Optional directory for device.key (default: ~/.yokotoken)
+ * @returns The decrypted vault master key (32 bytes)
+ * @throws KeyUnwrapError if decryption fails (wrong identity)
+ * @throws DeviceSecretMissingError if device.key is not found
+ * @throws Error if no link exists for the given provider+subject_id
+ */
+export async function unwrapMasterKey(db, provider, subjectId, deviceDir) {
+    // Ensure table exists
+    initOAuthLinksTable(db);
+    // Read device secret (throws DeviceSecretMissingError if missing)
+    const deviceSecret = readDeviceSecret(deviceDir);
+    // Look up the link
+    const row = queryOne(db, `SELECT wrap_salt, wrapped_key, nonce FROM oauth_links
+     WHERE provider = ? AND subject_id = ?`, [provider, subjectId]);
+    if (!row || !row.wrap_salt) {
+        throw new Error(`No OAuth link found for provider '${provider}' with subject '${subjectId}'. ` +
+            `Run 'unotoken auth link ${provider}' while the vault is unlocked to create a link.`);
+    }
+    // Extract stored values
+    const wrapSalt = Buffer.from(row.wrap_salt);
+    const wrappedKey = Buffer.from(row.wrapped_key);
+    const nonce = Buffer.from(row.nonce);
+    // Re-derive wrap key from device secret + stored salt
+    const wrapKey = deriveWrapKey(deviceSecret, wrapSalt, provider, subjectId);
+    // Decrypt master key
+    const masterKey = await decryptMasterKey(wrappedKey, nonce, wrapKey);
+    // Update last_used_at
+    db.run(`UPDATE oauth_links SET last_used_at = ? WHERE provider = ? AND subject_id = ?`, [new Date().toISOString(), provider, subjectId]);
+    // Securely zero the wrap key
+    try {
+        await ensureSodium();
+        sodium.memzero(new Uint8Array(wrapKey.buffer, wrapKey.byteOffset, wrapKey.byteLength));
+    }
+    catch {
+        // Best-effort secure zeroing
+    }
+    return masterKey;
+}
+/**
+ * List all linked OAuth providers for the current vault.
+ *
+ * @param db - sql.js database instance
+ * @returns Array of link rows (provider, subject_id, created_at, last_used_at)
+ */
+export function listOAuthLinks(db) {
+    initOAuthLinksTable(db);
+    const links = [];
+    const stmt = db.prepare(`SELECT provider, subject_id, wrap_salt, wrapped_key, nonce, created_at, last_used_at
+     FROM oauth_links ORDER BY created_at ASC`);
+    while (stmt.step()) {
+        const row = stmt.getAsObject();
+        links.push({
+            provider: row.provider,
+            subject_id: row.subject_id,
+            wrap_salt: Buffer.from(row.wrap_salt),
+            wrapped_key: Buffer.from(row.wrapped_key),
+            nonce: Buffer.from(row.nonce),
+            created_at: row.created_at,
+            last_used_at: row.last_used_at,
+        });
+    }
+    stmt.free();
+    return links;
+}
+/**
+ * Remove an OAuth link for a provider.
+ *
+ * @param db - sql.js database instance
+ * @param provider - OAuth provider name
+ * @param subjectId - Optional subject ID (if omitted, removes all links for the provider)
+ * @returns true if a row was deleted
+ */
+export function removeOAuthLink(db, provider, subjectId) {
+    initOAuthLinksTable(db);
+    // Count before delete
+    const before = queryOne(db, subjectId
+        ? `SELECT COUNT(*) as cnt FROM oauth_links WHERE provider = ? AND subject_id = ?`
+        : `SELECT COUNT(*) as cnt FROM oauth_links WHERE provider = ?`, subjectId ? [provider, subjectId] : [provider]);
+    if (subjectId) {
+        db.run(`DELETE FROM oauth_links WHERE provider = ? AND subject_id = ?`, [provider, subjectId]);
+    }
+    else {
+        db.run(`DELETE FROM oauth_links WHERE provider = ?`, [provider]);
+    }
+    return before.cnt > 0;
+}
+//# sourceMappingURL=key-wrap.js.map

package/dist/oauth/key-wrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-wrap.js","sourceRoot":"","sources":["../../src/oauth/key-wrap.ts"],"names":[],"mappings":"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"}

package/dist/oauth/pkce.d.ts

@@ -0,0 +1,29 @@
+/**
+ * PKCE (Proof Key for Code Exchange) utilities for OAuth 2.0.
+ *
+ * Uses Node's built-in crypto module — no external dependencies.
+ * Implements S256 method (SHA-256 of verifier as challenge).
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc7636
+ */
+export interface PKCEPair {
+    /** Random high-entropy string (43-128 chars, unreserved URI characters) */
+    verifier: string;
+    /** Base64url-encoded SHA-256 hash of the verifier */
+    challenge: string;
+    /** Always 'S256' */
+    method: 'S256';
+}
+/**
+ * Generate a PKCE verifier and challenge pair.
+ *
+ * The verifier is 64 bytes of random data, base64url-encoded (86 chars).
+ * The challenge is the SHA-256 hash of the verifier, base64url-encoded.
+ */
+export declare function generatePKCE(): PKCEPair;
+/**
+ * Compute the S256 challenge from a verifier.
+ * Useful for verification in tests.
+ */
+export declare function computeChallenge(verifier: string): string;
+//# sourceMappingURL=pkce.d.ts.map

package/dist/oauth/pkce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.d.ts","sourceRoot":"","sources":["../../src/oauth/pkce.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,WAAW,QAAQ;IACvB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,oBAAoB;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,QAAQ,CAIvC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEzD"}

package/dist/oauth/pkce.js

@@ -0,0 +1,34 @@
+/**
+ * PKCE (Proof Key for Code Exchange) utilities for OAuth 2.0.
+ *
+ * Uses Node's built-in crypto module — no external dependencies.
+ * Implements S256 method (SHA-256 of verifier as challenge).
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc7636
+ */
+import { randomBytes, createHash } from 'node:crypto';
+/**
+ * Generate a PKCE verifier and challenge pair.
+ *
+ * The verifier is 64 bytes of random data, base64url-encoded (86 chars).
+ * The challenge is the SHA-256 hash of the verifier, base64url-encoded.
+ */
+export function generatePKCE() {
+    const verifier = base64url(randomBytes(64));
+    const challenge = base64url(createHash('sha256').update(verifier).digest());
+    return { verifier, challenge, method: 'S256' };
+}
+/**
+ * Compute the S256 challenge from a verifier.
+ * Useful for verification in tests.
+ */
+export function computeChallenge(verifier) {
+    return base64url(createHash('sha256').update(verifier).digest());
+}
+/**
+ * Base64url encoding (RFC 4648 section 5) without padding.
+ */
+function base64url(buf) {
+    return buf.toString('base64url');
+}
+//# sourceMappingURL=pkce.js.map

package/dist/oauth/pkce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.js","sourceRoot":"","sources":["../../src/oauth/pkce.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAWtD;;;;;GAKG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,QAAQ,GAAG,SAAS,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC;IAC5C,MAAM,SAAS,GAAG,SAAS,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5E,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AACjD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,OAAO,SAAS,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;AACnE,CAAC;AAED;;GAEG;AACH,SAAS,SAAS,CAAC,GAAW;IAC5B,OAAO,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AACnC,CAAC"}

package/dist/oauth/provider.d.ts

@@ -0,0 +1,79 @@
+/**
+ * OAuth provider interface for unotoken.
+ *
+ * Each provider (Google, GitHub, etc.) implements this interface to
+ * plug into the generic OAuthFlow engine. The flow engine handles
+ * PKCE, callback server, and browser opening — providers just define
+ * their endpoints and token verification logic.
+ */
+import type { PKCEPair } from './pkce.js';
+/**
+ * Result of a successful OAuth authentication.
+ */
+export interface OAuthIdentity {
+    /** Provider name (e.g., 'google', 'github') */
+    provider: string;
+    /** Provider-specific unique user ID (e.g., Google sub, GitHub user ID) */
+    subjectId: string;
+    /** User's email address (if available) */
+    email?: string;
+    /** User's display name (if available) */
+    name?: string;
+}
+/**
+ * Token response from the OAuth token endpoint.
+ */
+export interface TokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in?: number;
+    refresh_token?: string;
+    id_token?: string;
+    scope?: string;
+}
+/**
+ * Provider interface — each OAuth provider must implement this.
+ */
+export interface OAuthProvider {
+    /** Provider identifier (e.g., 'google', 'github') */
+    readonly name: string;
+    /** OAuth client ID */
+    readonly clientId: string;
+    /** Requested scopes */
+    readonly scopes: string[];
+    /**
+     * Build the authorization URL for the browser redirect.
+     *
+     * @param redirectUri - The localhost callback URL (e.g., http://localhost:12345/callback)
+     * @param state - CSRF protection state parameter
+     * @param pkce - PKCE verifier/challenge pair
+     * @returns Full authorization URL to open in the browser
+     */
+    authorizeUrl(redirectUri: string, state: string, pkce: PKCEPair): string;
+    /** Token endpoint URL */
+    readonly tokenEndpoint: string;
+    /**
+     * Build the body parameters for the token exchange request.
+     *
+     * Most providers use the standard OAuth2 code exchange, but some (like GitHub)
+     * require additional parameters (e.g., client_secret).
+     *
+     * @param code - Authorization code from the callback
+     * @param redirectUri - The same redirect URI used in the authorize request
+     * @param pkce - PKCE pair (verifier is sent to prove possession)
+     * @returns URLSearchParams for the POST body
+     */
+    tokenRequestBody(code: string, redirectUri: string, pkce: PKCEPair): URLSearchParams;
+    /**
+     * Verify and extract identity from the token response.
+     *
+     * For OIDC providers (Google): verify the ID token signature, expiry, audience, issuer.
+     * For non-OIDC providers (GitHub): use the access token to call a user info endpoint.
+     *
+     * @param tokenResponse - Raw token response from the token endpoint
+     * @returns Verified identity
+     * @throws Error if verification fails
+     */
+    verifyIdentity(tokenResponse: TokenResponse): Promise<OAuthIdentity>;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/oauth/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/oauth/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE1C;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,sBAAsB;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,uBAAuB;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAE1B;;;;;;;OAOG;IACH,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;IAEzE,yBAAyB;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,eAAe,CAAC;IAErF;;;;;;;;;OASG;IACH,cAAc,CAAC,aAAa,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CACtE"}

package/dist/oauth/provider.js

@@ -0,0 +1,10 @@
+/**
+ * OAuth provider interface for unotoken.
+ *
+ * Each provider (Google, GitHub, etc.) implements this interface to
+ * plug into the generic OAuthFlow engine. The flow engine handles
+ * PKCE, callback server, and browser opening — providers just define
+ * their endpoints and token verification logic.
+ */
+export {};
+//# sourceMappingURL=provider.js.map