@noy-db/on-recovery 0.7.0-pre.9 → 0.8.0-pre.0

package/LICENSE

@@ -1,21 +1,202 @@
-MIT License
-
-Copyright (c) 2026 vLannaAi
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 vLannaAi
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1 @@
+noy-db — Copyright 2026 vLannaAi

package/README.md

@@ -14,10 +14,10 @@ pnpm add @noy-db/on-recovery
 
 **Protects against:**
 - Primary authentication becoming unavailable (forgotten secret, lost passkey device, OIDC provider down)
-- Code replay — each code burns on successful unlock by deleting its keyring entry
+- Code replay — the hub burns each entry on successful recovery
 
 **Does NOT protect against:**
-- Physical theft of printed codes — assume paper compromise → user calls `revokeAllRecoveryCodes` + re-enrolls
+- Physical theft of printed codes — assume paper compromise → call `db.team.rotateRecovery(vault, { profile: 'paper' })` for a fresh sheet (replaces, never appends; gated by the `rotate-recovery` policy gate)
 - User enrolling without actually printing — the calling application must enforce this UX
 
 Recovery codes should NEVER be the only unlock method on a vault. Enroll secret / WebAuthn / OIDC first, then recovery codes as a fallback.
@@ -38,127 +38,105 @@ Input is lenient: whitespace, hyphens, lowercase are all stripped before validat
 
 ## Security model
 
-Each code is processed through:
+This package is a **thin code-generator + parser layer over the hub's
+`mintPaperRecoveryEntry` primitive**. The crypto lives in the hub, and it
+wraps the vault's **DEK set** — never the KEK:
 
 ```
 wrappingKey = PBKDF2-SHA256(
   password   = normalizeCode(code),
-  salt       = perCodeRandomSalt,   // Stored alongside wrapped KEK
-  iterations = 600_000,              // Matches hub's secret derivation
+  salt       = perEntryRandomSalt,
+  iterations = 600_000,              // matches hub's secret derivation
   length     = 256                   // bits
 )
 
-wrappedKEK = AES-KW(kek, wrappingKey)
+entry = AES-GCM(dekSet, wrappingKey) + salt + codeId + enrolledAt
 ```
 
-The `wrappedKEK + salt + codeId` goes into the keyring under a `_recovery_<N>` entry. On unlock, PBKDF2 re-derives the wrapping key from the user-typed code + salt, and AES-KW unwraps the KEK.
+Entries live in the vault's `_meta/recovery-paper` document. On recovery the
+hub re-derives the wrapping key from the typed code, unwraps the DEK set, and
+re-wraps it under the user's **new** secret.
+
+> **History — why there is no KEK path.** Until `0.1.0-pre.8` this package
+> wrapped the KEK directly (`unwrapKEKFromRecovery`, `wrapKEKForRecovery`).
+> That required an **extractable KEK**, which the hub's key derivation
+> deliberately disallows — the same asymmetry that made `on-password`
+> unreachable from a real consumer. All unlock tiers were unified on the
+> wrap-DEKs primitive (#26 Path C, #38 Option A), and the KEK-wrapping API
+> was removed. Do not look for it; nothing here can hand you a KEK.
 
 ## Usage
 
-This package provides the **crypto layer only**. Storage, audit, rate-limiting, and burn-on-use are application-layer concerns handled by hub's keyring + audit-ledger APIs.
+This package does exactly three things: generate printable codes, parse and
+normalize user input, and format normalized codes for display. Storage,
+matching, burn-on-use, auditing, and rotation are all **hub** concerns.
 
 ### Enrollment (after primary unlock)
 
 ```ts
 import { generateRecoveryCodeSet } from '@noy-db/on-recovery'
 
-// After the user unlocks with secret, offer recovery-code enrollment
+// The DEK set proves possession and is what the codes wrap.
+const keyring = await db.team.getKeyring('acme')
 const { codes, entries } = await generateRecoveryCodeSet({
-  count: 10,        // 8-20 is reasonable; default 10
-  kek: currentKEK,  // The vault's currently-unwrapped KEK
+  deks: keyring.deks,
+  count: 10,          // 8-20 is reasonable; default 10
 })
 
 // Show `codes` to the user ONCE — print, download, copy. Do NOT store them.
 displayRecoveryCodes(codes)
-downloadRecoveryCodes(codes)
-
-// Persist `entries` to the vault's keyring. Each entry is safe to
-// store on disk — it holds only the salt + wrapped KEK + codeId.
-for (const entry of entries) {
-  await vault.keyring.put(`_recovery_${entry.codeId}`, entry)
-}
-
-// Write an audit-ledger entry
-await vault.ledger.append({
-  type: 'on-recovery:enroll',
-  actor: currentUserId,
-  codeCount: entries.length,
-  timestamp: new Date().toISOString(),
-})
+
+// Persist `entries` — each holds only salt + wrapped DEK set + codeId,
+// safe to store. The hub appends them to `_meta/recovery-paper`.
+await db.team.enrollRecovery('acme', { profile: 'paper', entries })
 ```
 
-### Unlock (when primary auth is unavailable)
+### Recovery (when primary auth is unavailable)
+
+`parseRecoveryCode` classifies input **before** any expensive derivation, so
+a transcription error never counts against a rate limit:
 
 ```ts
-import { parseRecoveryCode, unwrapKEKFromRecovery } from '@noy-db/on-recovery'
+import { parseRecoveryCode } from '@noy-db/on-recovery'
 
 const parsed = parseRecoveryCode(userInput)
+if (parsed.status === 'invalid-format')   return showError('not a recovery code')
+if (parsed.status === 'invalid-checksum') return showError('check for typos')   // transcription, not a guess
+```
+
+The recovery itself is one hub call. It finds the matching entry, burns it,
+sets the new secret, and by default **auto-rotates the remaining codes** so
+the sheet in the safe stays fully usable:
 
-if (parsed.status === 'invalid-format') {
-  // User typed junk — show "not a valid recovery code" without counting against rate limit
-  return showError('format')
-}
-if (parsed.status === 'invalid-checksum') {
-  // Well-formed but checksum wrong — transcription error, not a guess
-  return showError('checksum')
-}
-
-// Find which enrolled entry this code matches
-const allEntries = await vault.keyring.list({ prefix: '_recovery_' })
-
-for (const entry of allEntries) {
-  try {
-    const kek = await unwrapKEKFromRecovery(parsed.code, entry)
-
-    // Match! Burn this entry — delete the keyring record so the code
-    // can never be replayed.
-    await vault.keyring.delete(`_recovery_${entry.codeId}`)
-
-    // Write an audit-ledger entry
-    await vault.ledger.append({
-      type: 'on-recovery:unlock',
-      actor: currentUserId,
-      codesRemaining: allEntries.length - 1,
-      timestamp: new Date().toISOString(),
-    })
-
-    return kek
-  } catch {
-    // Wrong entry, try next
-  }
-}
-
-// No matching entry — counts against the host app's rate limit
-await vault.ledger.append({
-  type: 'on-recovery:unlock-failed',
-  actor: currentUserId,
-  reason: 'not-found',
-  timestamp: new Date().toISOString(),
+```ts
+const { newCodes } = await db.recoverSecret('acme', {
+  newSecret,
+  recoveryProof: { profile: 'paper', payload: { code: parsed.code } },
 })
-throw new Error('no matching recovery code')
+if (newCodes.length > 0) showCodesToUser(newCodes)   // show-once, same as enrollment
 ```
 
-### Revocation (after a suspected paper leak)
+### Fresh sheet (lost printout / suspected paper leak)
 
 ```ts
-// Scan all recovery entries, delete each.
-const allEntries = await vault.keyring.list({ prefix: '_recovery_' })
-for (const entry of allEntries) {
-  await vault.keyring.delete(`_recovery_${entry.codeId}`)
-}
-// Optionally re-enroll a fresh set.
+const { newCodes } = await db.team.rotateRecovery('acme', { profile: 'paper' })
+showCodesToUser(newCodes)
 ```
 
+Replaces (never appends) the paper sheet in a single envelope write. Under
+`STRICT_POLICY` this requires an off-device factor proof, so a stolen
+unlocked laptop cannot silently mint a sheet for the attacker.
+
 ## API
 
 ```ts
 // Generate a full enrollment
 async function generateRecoveryCodeSet(options: {
-  count?: number         // Default 10, clamped to 1..100
-  kek: CryptoKey         // Currently-unwrapped KEK
+  count?: number                 // Default 10, clamped to 1..100
+  deks: Map<string, CryptoKey>   // The vault's current DEK set
 }): Promise<{
-  codes: string[]        // Show to user once, then forget
-  entries: RecoveryCodeEntry[]  // Persist to keyring
+  codes: string[]                // Show to user once, then forget
+  entries: PaperRecoveryEntry[]  // Persist via db.team.enrollRecovery
 }>
 
 // Parse + normalize user input
@@ -169,31 +147,17 @@ type ParseResult =
   | { status: 'invalid-checksum' }        // Format OK, checksum wrong
   | { status: 'invalid-format' }          // Not a valid code shape
 
-// Attempt to unwrap the KEK with a code + an entry; throws on mismatch
-async function unwrapKEKFromRecovery(
-  code: string,              // The normalized code from parseRecoveryCode
-  entry: RecoveryCodeEntry,  // One of the enrolled entries
-): Promise<CryptoKey>
-
-// Lower-level helpers (for advanced use cases)
+// Re-hyphenate a normalized code for display
 function formatRecoveryCode(normalized: string): string
-async function deriveRecoveryWrappingKey(code: string, salt: Uint8Array): Promise<CryptoKey>
-async function wrapKEKForRecovery(kek: CryptoKey, code: string, salt: Uint8Array): Promise<Uint8Array>
-
-interface RecoveryCodeEntry {
-  codeId: string        // ULID — caller uses this to delete the entry on burn
-  salt: string          // Base64
-  wrappedKEK: string    // Base64
-  enrolledAt: string    // ISO timestamp
-}
 ```
 
-## Performance
+`PaperRecoveryEntry` (`{ codeId, enrolledAt, salt, wrapped DEK blob }`) is the
+hub's type — this package mints it via the hub and never defines its own.
 
-PBKDF2 with 600K iterations takes ~500ms per derive on modern hardware. Generating 10 codes enrolls in ~5 seconds (serial) — acceptable for a one-time enrollment flow; show a loading indicator. Unlock is a single derive per attempt (~500ms).
+## Performance
 
-If you need faster enrollment (e.g., a CLI test), you can parallelize via `Promise.all`.
+PBKDF2 with 600K iterations takes ~500ms per derive on modern hardware. Generating 10 codes enrolls in ~5 seconds (serial) — acceptable for a one-time enrollment flow; show a loading indicator. Recovery is a single derive per attempt (~500ms).
 
 ## License
 
-MIT
+Apache-2.0

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@noy-db/on-recovery",
-  "version": "0.7.0-pre.9",
+  "version": "0.8.0-pre.0",
   "description": "One-time printable recovery codes for noy-db — last-resort vault unlock when the secret, passkey, and OIDC provider are all unavailable. Base32 + checksum codes, PBKDF2-derived wrapping keys, burn-on-use. Part of the @noy-db/on-* authentication family.",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "author": "vLannaAi <vicio@lanna.ai>",
-  "homepage": "https://github.com/vLannaAi/noy-db/tree/main/packages/on-recovery#readme",
+  "homepage": "https://github.com/noy-db/on/tree/main/on-recovery#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/vLannaAi/noy-db.git",
-    "directory": "packages/on-recovery"
+    "url": "git+https://github.com/noy-db/on.git",
+    "directory": "on-recovery"
   },
   "bugs": {
-    "url": "https://github.com/vLannaAi/noy-db/issues"
+    "url": "https://github.com/noy-db/on/issues"
   },
   "type": "module",
   "sideEffects": false,
@@ -26,16 +26,18 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "NOTICE"
   ],
   "engines": {
     "node": ">=22.0.0"
   },
   "peerDependencies": {
-    "@noy-db/hub": "^0.7.0-pre.9"
+    "@noy-db/hub": "^0.7.0 || ^0.7.1-pre.0 || ^0.8.0-pre.0"
   },
   "devDependencies": {
-    "@noy-db/hub": "0.7.0-pre.9"
+    "@noy-db/hub": "0.8.0-pre.0",
+    "happy-dom": "^18.0.0"
   },
   "keywords": [
     "noy-db",