@noy-db/on-magic-link 0.1.0-pre.7 → 0.1.0-pre.8

package/dist/index.d.cts

@@ -1,6 +1,214 @@
-import { NoydbStore, MagicLinkGrantPayload, UnlockedKeyring, Vault } from '@noy-db/hub';
+import { NoydbStore, createNoydb, Noydb, Role, FactorProof, MagicLinkGrantPayload, UnlockedKeyring, Vault } from '@noy-db/hub';
 export { MAGIC_LINK_GRANTS_COLLECTION, MagicLinkGrantPayload, deriveMagicLinkContentKey } from '@noy-db/hub';
 
+/**
+ * **Invite + peer-recovery primitives** — issue #32.
+ *
+ * Layered on top of `db.grant` (for invite, mints a NEW user) and
+ * `db.recoverUser` (for peer-recovery, rewraps an EXISTING user under
+ * a fresh temp passphrase). These flows are SIBLINGS of the existing
+ * delegation-grant primitives in `./index.ts` — different threat
+ * model, different on-disk audit shape, no server-held secret.
+ *
+ * ## Threat model
+ *
+ * The temp passphrase travels in the **URL fragment** — server-blind
+ * transport (fragments don't traverse TLS proxies, don't appear in
+ * access logs). Trade-off: any party who sees the URL can claim the
+ * invite once. Single-use semantics close the window: `acceptInvite`
+ * rotates the passphrase atomically, marking the audit doc accepted —
+ * a second `acceptInvite` call rejects.
+ *
+ * ## What this module does NOT do
+ *
+ * - Send emails / construct HTTPS URLs (that's the application layer)
+ * - Validate the invite under HTTPS (caller's responsibility)
+ * - Coordinate with a server-held secret (delegation grants do that;
+ *   invite is server-blind by design)
+ *
+ * @see #32 #33 #34
+ *
+ * @module
+ */
+
+/** Whether the payload mints a NEW user (invite) or rewraps an existing one (peer-recovery). */
+type InviteKind = 'invite' | 'peer-recovery';
+/**
+ * Serializable payload encoded into the URL fragment. The temp
+ * passphrase is the secret; the rest is metadata the recipient
+ * needs to open the right vault as the right user.
+ */
+interface InvitePayload {
+    /** ULID identifying this invite — used to look up the audit doc. */
+    readonly tokenId: string;
+    readonly vault: string;
+    readonly userId: string;
+    readonly displayName?: string;
+    readonly role?: Role;
+    readonly kind: InviteKind;
+    /** Issuer's userId (for forensics; not enforced cryptographically). */
+    readonly issuer: string;
+    /** Single-use temporary passphrase — replaced on `acceptInvite`. */
+    readonly tempPhrase: string;
+    readonly expiresAt: string;
+}
+/** Audit doc persisted at `_meta/invite-audit-<tokenId>`. */
+interface InviteAuditDoc {
+    readonly _noydb_invite_audit: 1;
+    readonly tokenId: string;
+    readonly kind: InviteKind;
+    readonly issuer: string;
+    readonly target: string;
+    readonly expiresAt: string;
+    readonly issuedAt: string;
+    readonly revokedAt?: string;
+    readonly acceptedAt?: string;
+}
+interface IssueInviteOptions {
+    readonly userId: string;
+    readonly displayName: string;
+    readonly role: Role;
+    readonly ttlMs?: number;
+    /** Override the generated temp phrase (rare; deterministic tests). */
+    readonly tempPhrase?: string;
+}
+interface IssuePeerRecoveryOptions {
+    readonly userId: string;
+    readonly displayName?: string;
+    readonly role?: Role;
+    readonly ttlMs?: number;
+    readonly tempPhrase?: string;
+}
+interface IssueInviteResult {
+    readonly payload: InvitePayload;
+    /**
+     * URL-fragment-safe base64url encoding of the JSON payload. Embed
+     * after a `#` in the application's invite URL. Decoded back at
+     * accept time via `decodeInvitePayload`.
+     */
+    readonly encoded: string;
+}
+interface AcceptInviteOptions {
+    /**
+     * The recipient's NoydbStore. Typically the same shared store the
+     * issuer used (e.g. a sync-peer pointing at a common backend) — the
+     * recipient must reach the same `_keyring/<userId>` and
+     * `_meta/invite-audit-<tokenId>` documents.
+     */
+    readonly store: NoydbStore;
+    /**
+     * The recipient's chosen new passphrase. `acceptInvite` rotates
+     * the temp phrase to this value atomically before returning. Must
+     * pass the vault's phrase strength policy (or the recipient must
+     * pass `validatePassphrase: false` via the underlying createNoydb
+     * options — currently exposed via `noydbOptions`).
+     */
+    readonly newPhrase: string;
+    /**
+     * Reference clock for TTL evaluation. Production callers leave
+     * this `undefined`; tests pass a fixed date.
+     */
+    readonly now?: Date;
+    /**
+     * Extra options forwarded to `createNoydb` when the recipient's
+     * session opens. Useful for `policy`, `validatePassphrase`, or
+     * `sessionPolicy` tweaks the application layer wants in scope.
+     */
+    readonly noydbOptions?: Omit<Parameters<typeof createNoydb>[0], 'store' | 'user' | 'secret'>;
+}
+interface AcceptInviteResult {
+    readonly db: Noydb;
+    readonly payload: InvitePayload;
+}
+declare class InviteExpiredError extends Error {
+    readonly expiresAt: string;
+    readonly code: "INVITE_EXPIRED";
+    constructor(expiresAt: string);
+}
+declare class InviteRevokedError extends Error {
+    readonly tokenId: string;
+    readonly revokedAt: string;
+    readonly code: "INVITE_REVOKED";
+    constructor(tokenId: string, revokedAt: string);
+}
+declare class InviteAlreadyAcceptedError extends Error {
+    readonly tokenId: string;
+    readonly acceptedAt: string;
+    readonly code: "INVITE_ALREADY_ACCEPTED";
+    constructor(tokenId: string, acceptedAt: string);
+}
+declare class InviteAuditMissingError extends Error {
+    readonly tokenId: string;
+    readonly code: "INVITE_AUDIT_MISSING";
+    constructor(tokenId: string);
+}
+/**
+ * Mint an invite for a NEW user. Generates a random temp phrase,
+ * calls `db.grant({ userId, passphrase: tempPhrase })`, writes the
+ * audit doc, and returns the URL-encodable payload.
+ *
+ * The recipient claims via `acceptInvite(encoded, { store, newPhrase })`;
+ * the rotation inside `acceptInvite` invalidates the temp phrase
+ * (single-use by construction).
+ *
+ * @throws Whatever `db.grant` throws (PrivilegeEscalationError,
+ *         WeakPassphraseError if the temp phrase fails policy, …)
+ */
+declare function issueInvite(db: Noydb, vault: string, options: IssueInviteOptions): Promise<IssueInviteResult>;
+/**
+ * Mint a peer-recovery for an EXISTING user. Generates a random temp
+ * phrase, calls `db.recoverUser` (atomic; closes the partial-failure
+ * window of compose-from-primitives), writes the audit doc, returns
+ * the payload.
+ *
+ * Owner→owner is allowed (the policy gate `peer-recover-user` carries
+ * the freshness factor). The `factors` argument forwards to the gate.
+ */
+declare function issuePeerRecovery(db: Noydb, vault: string, options: IssuePeerRecoveryOptions, factors?: {
+    factors?: ReadonlyArray<FactorProof>;
+    sharedDevice?: boolean;
+}): Promise<IssueInviteResult>;
+/**
+ * Mark an outstanding invite as revoked. After this, `acceptInvite`
+ * for the same token rejects with `InviteRevokedError` BEFORE opening
+ * any session — closes #32's "revoked-link silent shadow keyring"
+ * defense (without the audit doc check, a revoked link could fall
+ * through to `createNoydb`'s no-keyring auto-create path and create
+ * a fresh empty vault).
+ *
+ * Idempotent — revoking an already-revoked invite is a no-op.
+ *
+ * Note: this does NOT delete the granted/recovered keyring; it only
+ * marks the invite token as unusable. To fully cancel the invite,
+ * call `db.revoke(vault, { userId })` separately. The two are split
+ * because peer-recovery doesn't have a "cancel" — the target user
+ * already existed.
+ */
+declare function revokeInvite(db: Noydb, vault: string, encodedOrPayload: string | InvitePayload): Promise<void>;
+/**
+ * Open the recipient's session under the invite. Validates TTL +
+ * revoke + already-accepted, opens `createNoydb` with the temp
+ * phrase, immediately rotates to `newPhrase`, marks the audit doc
+ * accepted, returns the live `Noydb` instance.
+ *
+ * Single-use is enforced two ways:
+ *   1. The rotation inside this function invalidates the temp phrase.
+ *   2. The audit doc's `acceptedAt` field is set on success — a
+ *      second `acceptInvite` call sees it and throws
+ *      `InviteAlreadyAcceptedError`.
+ *
+ * @throws {@link InviteExpiredError} when TTL has passed.
+ * @throws {@link InviteRevokedError} when the issuer has revoked.
+ * @throws {@link InviteAlreadyAcceptedError} on second call.
+ * @throws {@link InviteAuditMissingError} when no audit doc — closes
+ *         #32's revoked-link-shadow-keyring defense.
+ */
+declare function acceptInvite(encoded: string, options: AcceptInviteOptions): Promise<AcceptInviteResult>;
+/** Encode the payload as a URL-fragment-safe base64url string. */
+declare function encodeInvitePayload(payload: InvitePayload): string;
+/** Decode a base64url string back to an InvitePayload. */
+declare function decodeInvitePayload(encoded: string): InvitePayload;
+
 /**
  * **@noy-db/on-magic-link** — one-time-link viewer unlock for noy-db.
  *
@@ -289,4 +497,4 @@ declare function readMagicLinkGrant(options: {
     readonly recordId: string;
 }): Promise<MagicLinkGrantPayload | null>;
 
-export { type ClaimMagicLinkDelegationOptions, type ClaimMagicLinkDelegationResult, type ClaimedMagicLinkGrant, type CreateMagicLinkOptions, type IssueMagicLinkDelegationOptions, type IssueMagicLinkDelegationResult, MAGIC_LINK_DEFAULT_TTL_MS, type MagicLinkGrantSpec, type MagicLinkToken, buildMagicLinkKeyring, claimMagicLinkDelegation, createMagicLinkToken, deriveMagicLinkKEK, inspectMagicLinkDelegation, isMagicLinkValid, issueMagicLinkDelegation, readMagicLinkGrant, revokeMagicLinkDelegation };
+export { type AcceptInviteOptions, type AcceptInviteResult, type ClaimMagicLinkDelegationOptions, type ClaimMagicLinkDelegationResult, type ClaimedMagicLinkGrant, type CreateMagicLinkOptions, InviteAlreadyAcceptedError, type InviteAuditDoc, InviteAuditMissingError, InviteExpiredError, type InviteKind, type InvitePayload, InviteRevokedError, type IssueInviteOptions, type IssueInviteResult, type IssueMagicLinkDelegationOptions, type IssueMagicLinkDelegationResult, type IssuePeerRecoveryOptions, MAGIC_LINK_DEFAULT_TTL_MS, type MagicLinkGrantSpec, type MagicLinkToken, acceptInvite, buildMagicLinkKeyring, claimMagicLinkDelegation, createMagicLinkToken, decodeInvitePayload, deriveMagicLinkKEK, encodeInvitePayload, inspectMagicLinkDelegation, isMagicLinkValid, issueInvite, issueMagicLinkDelegation, issuePeerRecovery, readMagicLinkGrant, revokeInvite, revokeMagicLinkDelegation };

package/dist/index.d.ts

@@ -1,6 +1,214 @@
-import { NoydbStore, MagicLinkGrantPayload, UnlockedKeyring, Vault } from '@noy-db/hub';
+import { NoydbStore, createNoydb, Noydb, Role, FactorProof, MagicLinkGrantPayload, UnlockedKeyring, Vault } from '@noy-db/hub';
 export { MAGIC_LINK_GRANTS_COLLECTION, MagicLinkGrantPayload, deriveMagicLinkContentKey } from '@noy-db/hub';
 
+/**
+ * **Invite + peer-recovery primitives** — issue #32.
+ *
+ * Layered on top of `db.grant` (for invite, mints a NEW user) and
+ * `db.recoverUser` (for peer-recovery, rewraps an EXISTING user under
+ * a fresh temp passphrase). These flows are SIBLINGS of the existing
+ * delegation-grant primitives in `./index.ts` — different threat
+ * model, different on-disk audit shape, no server-held secret.
+ *
+ * ## Threat model
+ *
+ * The temp passphrase travels in the **URL fragment** — server-blind
+ * transport (fragments don't traverse TLS proxies, don't appear in
+ * access logs). Trade-off: any party who sees the URL can claim the
+ * invite once. Single-use semantics close the window: `acceptInvite`
+ * rotates the passphrase atomically, marking the audit doc accepted —
+ * a second `acceptInvite` call rejects.
+ *
+ * ## What this module does NOT do
+ *
+ * - Send emails / construct HTTPS URLs (that's the application layer)
+ * - Validate the invite under HTTPS (caller's responsibility)
+ * - Coordinate with a server-held secret (delegation grants do that;
+ *   invite is server-blind by design)
+ *
+ * @see #32 #33 #34
+ *
+ * @module
+ */
+
+/** Whether the payload mints a NEW user (invite) or rewraps an existing one (peer-recovery). */
+type InviteKind = 'invite' | 'peer-recovery';
+/**
+ * Serializable payload encoded into the URL fragment. The temp
+ * passphrase is the secret; the rest is metadata the recipient
+ * needs to open the right vault as the right user.
+ */
+interface InvitePayload {
+    /** ULID identifying this invite — used to look up the audit doc. */
+    readonly tokenId: string;
+    readonly vault: string;
+    readonly userId: string;
+    readonly displayName?: string;
+    readonly role?: Role;
+    readonly kind: InviteKind;
+    /** Issuer's userId (for forensics; not enforced cryptographically). */
+    readonly issuer: string;
+    /** Single-use temporary passphrase — replaced on `acceptInvite`. */
+    readonly tempPhrase: string;
+    readonly expiresAt: string;
+}
+/** Audit doc persisted at `_meta/invite-audit-<tokenId>`. */
+interface InviteAuditDoc {
+    readonly _noydb_invite_audit: 1;
+    readonly tokenId: string;
+    readonly kind: InviteKind;
+    readonly issuer: string;
+    readonly target: string;
+    readonly expiresAt: string;
+    readonly issuedAt: string;
+    readonly revokedAt?: string;
+    readonly acceptedAt?: string;
+}
+interface IssueInviteOptions {
+    readonly userId: string;
+    readonly displayName: string;
+    readonly role: Role;
+    readonly ttlMs?: number;
+    /** Override the generated temp phrase (rare; deterministic tests). */
+    readonly tempPhrase?: string;
+}
+interface IssuePeerRecoveryOptions {
+    readonly userId: string;
+    readonly displayName?: string;
+    readonly role?: Role;
+    readonly ttlMs?: number;
+    readonly tempPhrase?: string;
+}
+interface IssueInviteResult {
+    readonly payload: InvitePayload;
+    /**
+     * URL-fragment-safe base64url encoding of the JSON payload. Embed
+     * after a `#` in the application's invite URL. Decoded back at
+     * accept time via `decodeInvitePayload`.
+     */
+    readonly encoded: string;
+}
+interface AcceptInviteOptions {
+    /**
+     * The recipient's NoydbStore. Typically the same shared store the
+     * issuer used (e.g. a sync-peer pointing at a common backend) — the
+     * recipient must reach the same `_keyring/<userId>` and
+     * `_meta/invite-audit-<tokenId>` documents.
+     */
+    readonly store: NoydbStore;
+    /**
+     * The recipient's chosen new passphrase. `acceptInvite` rotates
+     * the temp phrase to this value atomically before returning. Must
+     * pass the vault's phrase strength policy (or the recipient must
+     * pass `validatePassphrase: false` via the underlying createNoydb
+     * options — currently exposed via `noydbOptions`).
+     */
+    readonly newPhrase: string;
+    /**
+     * Reference clock for TTL evaluation. Production callers leave
+     * this `undefined`; tests pass a fixed date.
+     */
+    readonly now?: Date;
+    /**
+     * Extra options forwarded to `createNoydb` when the recipient's
+     * session opens. Useful for `policy`, `validatePassphrase`, or
+     * `sessionPolicy` tweaks the application layer wants in scope.
+     */
+    readonly noydbOptions?: Omit<Parameters<typeof createNoydb>[0], 'store' | 'user' | 'secret'>;
+}
+interface AcceptInviteResult {
+    readonly db: Noydb;
+    readonly payload: InvitePayload;
+}
+declare class InviteExpiredError extends Error {
+    readonly expiresAt: string;
+    readonly code: "INVITE_EXPIRED";
+    constructor(expiresAt: string);
+}
+declare class InviteRevokedError extends Error {
+    readonly tokenId: string;
+    readonly revokedAt: string;
+    readonly code: "INVITE_REVOKED";
+    constructor(tokenId: string, revokedAt: string);
+}
+declare class InviteAlreadyAcceptedError extends Error {
+    readonly tokenId: string;
+    readonly acceptedAt: string;
+    readonly code: "INVITE_ALREADY_ACCEPTED";
+    constructor(tokenId: string, acceptedAt: string);
+}
+declare class InviteAuditMissingError extends Error {
+    readonly tokenId: string;
+    readonly code: "INVITE_AUDIT_MISSING";
+    constructor(tokenId: string);
+}
+/**
+ * Mint an invite for a NEW user. Generates a random temp phrase,
+ * calls `db.grant({ userId, passphrase: tempPhrase })`, writes the
+ * audit doc, and returns the URL-encodable payload.
+ *
+ * The recipient claims via `acceptInvite(encoded, { store, newPhrase })`;
+ * the rotation inside `acceptInvite` invalidates the temp phrase
+ * (single-use by construction).
+ *
+ * @throws Whatever `db.grant` throws (PrivilegeEscalationError,
+ *         WeakPassphraseError if the temp phrase fails policy, …)
+ */
+declare function issueInvite(db: Noydb, vault: string, options: IssueInviteOptions): Promise<IssueInviteResult>;
+/**
+ * Mint a peer-recovery for an EXISTING user. Generates a random temp
+ * phrase, calls `db.recoverUser` (atomic; closes the partial-failure
+ * window of compose-from-primitives), writes the audit doc, returns
+ * the payload.
+ *
+ * Owner→owner is allowed (the policy gate `peer-recover-user` carries
+ * the freshness factor). The `factors` argument forwards to the gate.
+ */
+declare function issuePeerRecovery(db: Noydb, vault: string, options: IssuePeerRecoveryOptions, factors?: {
+    factors?: ReadonlyArray<FactorProof>;
+    sharedDevice?: boolean;
+}): Promise<IssueInviteResult>;
+/**
+ * Mark an outstanding invite as revoked. After this, `acceptInvite`
+ * for the same token rejects with `InviteRevokedError` BEFORE opening
+ * any session — closes #32's "revoked-link silent shadow keyring"
+ * defense (without the audit doc check, a revoked link could fall
+ * through to `createNoydb`'s no-keyring auto-create path and create
+ * a fresh empty vault).
+ *
+ * Idempotent — revoking an already-revoked invite is a no-op.
+ *
+ * Note: this does NOT delete the granted/recovered keyring; it only
+ * marks the invite token as unusable. To fully cancel the invite,
+ * call `db.revoke(vault, { userId })` separately. The two are split
+ * because peer-recovery doesn't have a "cancel" — the target user
+ * already existed.
+ */
+declare function revokeInvite(db: Noydb, vault: string, encodedOrPayload: string | InvitePayload): Promise<void>;
+/**
+ * Open the recipient's session under the invite. Validates TTL +
+ * revoke + already-accepted, opens `createNoydb` with the temp
+ * phrase, immediately rotates to `newPhrase`, marks the audit doc
+ * accepted, returns the live `Noydb` instance.
+ *
+ * Single-use is enforced two ways:
+ *   1. The rotation inside this function invalidates the temp phrase.
+ *   2. The audit doc's `acceptedAt` field is set on success — a
+ *      second `acceptInvite` call sees it and throws
+ *      `InviteAlreadyAcceptedError`.
+ *
+ * @throws {@link InviteExpiredError} when TTL has passed.
+ * @throws {@link InviteRevokedError} when the issuer has revoked.
+ * @throws {@link InviteAlreadyAcceptedError} on second call.
+ * @throws {@link InviteAuditMissingError} when no audit doc — closes
+ *         #32's revoked-link-shadow-keyring defense.
+ */
+declare function acceptInvite(encoded: string, options: AcceptInviteOptions): Promise<AcceptInviteResult>;
+/** Encode the payload as a URL-fragment-safe base64url string. */
+declare function encodeInvitePayload(payload: InvitePayload): string;
+/** Decode a base64url string back to an InvitePayload. */
+declare function decodeInvitePayload(encoded: string): InvitePayload;
+
 /**
  * **@noy-db/on-magic-link** — one-time-link viewer unlock for noy-db.
  *
@@ -289,4 +497,4 @@ declare function readMagicLinkGrant(options: {
     readonly recordId: string;
 }): Promise<MagicLinkGrantPayload | null>;
 
-export { type ClaimMagicLinkDelegationOptions, type ClaimMagicLinkDelegationResult, type ClaimedMagicLinkGrant, type CreateMagicLinkOptions, type IssueMagicLinkDelegationOptions, type IssueMagicLinkDelegationResult, MAGIC_LINK_DEFAULT_TTL_MS, type MagicLinkGrantSpec, type MagicLinkToken, buildMagicLinkKeyring, claimMagicLinkDelegation, createMagicLinkToken, deriveMagicLinkKEK, inspectMagicLinkDelegation, isMagicLinkValid, issueMagicLinkDelegation, readMagicLinkGrant, revokeMagicLinkDelegation };
+export { type AcceptInviteOptions, type AcceptInviteResult, type ClaimMagicLinkDelegationOptions, type ClaimMagicLinkDelegationResult, type ClaimedMagicLinkGrant, type CreateMagicLinkOptions, InviteAlreadyAcceptedError, type InviteAuditDoc, InviteAuditMissingError, InviteExpiredError, type InviteKind, type InvitePayload, InviteRevokedError, type IssueInviteOptions, type IssueInviteResult, type IssueMagicLinkDelegationOptions, type IssueMagicLinkDelegationResult, type IssuePeerRecoveryOptions, MAGIC_LINK_DEFAULT_TTL_MS, type MagicLinkGrantSpec, type MagicLinkToken, acceptInvite, buildMagicLinkKeyring, claimMagicLinkDelegation, createMagicLinkToken, decodeInvitePayload, deriveMagicLinkKEK, encodeInvitePayload, inspectMagicLinkDelegation, isMagicLinkValid, issueInvite, issueMagicLinkDelegation, issuePeerRecovery, readMagicLinkGrant, revokeInvite, revokeMagicLinkDelegation };