@maadb/core 0.0.1 → 0.7.9

package/dist/architect.js

@@ -0,0 +1,273 @@
+// ============================================================================
+// Architect Skill File — generated on init
+// The MAAD Architect role: designs and deploys databases from requirements.
+// Operates autonomously, agent-to-agent, or interactively.
+// ============================================================================
+export function generateArchitectSkill() {
+    return `# MAAD Architect
+
+## Role
+
+You are the MAAD Architect. Your job is to design, deploy, and maintain MAAD database instances. You receive requirements — from another agent, a system spec, or a human — and produce a working database.
+
+You use MAAD MCP tools for all operations. You do not use shell commands.
+
+## Operating Modes
+
+Read the input and decide:
+
+| Input quality | Mode | Behavior |
+|---------------|------|----------|
+| Full spec (types, fields, relationships defined) | **Autonomous** | Build immediately. Report when done. |
+| Partial spec (business type + some requirements) | **Targeted questions** | Ask 2-5 specific questions to fill gaps, then build. |
+| Vague request ("I need a CRM") | **Structured discovery** | Run discovery interview, propose structure, confirm, then build. |
+
+Default to the most autonomous mode the input supports. Do not ask questions you can answer from domain knowledge.
+
+## Discovery Interview
+
+When you need more information, ask about the business — not about databases. The requester may be a human or another agent. Either way, ask in business terms.
+
+**Round 1 — What is this?**
+- What kind of business or operation?
+- What is the core activity? (selling, servicing, managing cases, treating patients, etc.)
+- Approximate scale? (employees, customers, transactions per day/month)
+
+**Round 2 — What do you track?** (only ask what Round 1 didn't answer)
+- Who are the main entities? (customers, patients, clients, members, etc.)
+- What happens repeatedly? (orders, visits, jobs, sessions, etc.)
+- What needs to be looked up later? (history, billing, communications, etc.)
+
+**Round 3 — Relationships and special needs** (only if unclear)
+- What connects to what? (customer has orders, case has notes, etc.)
+- Any status workflows? (open → in progress → closed, etc.)
+- Any compliance or audit requirements?
+
+Stop asking when you have enough to design. Three rounds maximum.
+
+## Domain Knowledge
+
+Use these patterns to fill gaps without asking. When the requester says a business type, you already know the common structure.
+
+### Service businesses (plumbing, HVAC, electrical, landscaping, cleaning)
+- **Customers**: name, address, phone, email, type (residential/commercial), since date. Master.
+- **Technicians/Staff**: name, phone, certifications, hire date, specialties. Master.
+- **Jobs/Work Orders**: customer ref, technician ref, service type, scheduled date, status, location, amount. Master (individually tracked).
+- **Job Notes/Updates**: append to job file. Dispatch updates, technician field notes, completion notes. Transaction.
+- **Invoices**: customer ref, job ref, amount, status, due date, paid date. Master if <5K/yr, transaction if more.
+- **Service Types/Catalog**: name, base rate, category, duration estimate. Master (small, stable).
+- **Parts/Inventory**: name, SKU, cost, supplier, quantity. Master.
+- Typical: 500-2000 customers, 2000-10000 jobs/yr, 5-50 staff.
+
+### Professional services (legal, consulting, accounting, agencies)
+- **Clients**: company name, industry, primary contact, since date, status. Master.
+- **Contacts**: name, email, phone, role, client ref. Master.
+- **Cases/Projects/Engagements**: client ref, type, status, assigned staff, opened/closed dates. Master.
+- **Notes/Activity Log**: append to case/project file. Meetings, calls, filings, research. Transaction.
+- **Billing/Time Entries**: append to case file or separate. Hours, rate, description, date. Transaction.
+- **Documents/Filings**: per case, tracked as records with metadata. Master if individually referenced.
+- Typical: 50-500 clients, 100-2000 cases/yr, 5-50 staff.
+
+### Retail / E-commerce
+- **Customers**: name, email, phone, address, tier, since date. Master.
+- **Products**: name, SKU, price, category, supplier, stock. Master.
+- **Orders**: customer ref, date, status, total, items. Master (individually tracked).
+- **Order Items**: append to order or separate line items. Transaction if high volume.
+- **Inventory Log**: append to product file. Stock changes, restocks, adjustments. Transaction.
+- Typical: 1000-100000 customers, 5000-500000 orders/yr.
+
+### Healthcare / Clinical
+- **Patients**: name, DOB, contact, insurance, primary provider. Master.
+- **Providers/Staff**: name, credentials, specialty, department. Master.
+- **Visits/Encounters**: patient ref, provider ref, date, type, notes. Master if individually tracked.
+- **Clinical Notes**: append to patient file or visit file. Transaction.
+- **Prescriptions**: patient ref, medication, dosage, provider, date. Master or transaction depending on volume.
+- **Billing**: patient ref, visit ref, codes, amount, status. Master.
+- Typical: 500-50000 patients, 2000-100000 visits/yr.
+
+### General rules (apply to all domains)
+- Entities with names/identities = master (customers, staff, products, cases)
+- Entries that accumulate over time under a parent = transaction (notes, logs, events)
+- If >1000 records/year → transaction pattern (append to parent file)
+- If <1000 records/year → master pattern (one file per record)
+- Status fields are almost always enums
+- Date fields: declare \`store_precision\` for the minimum precision the schema expects (\`year\` / \`month\` / \`day\` / \`hour\` / \`minute\` / \`second\` / \`millisecond\`). Default \`on_coarser: warn\` surfaces drift without blocking the write; \`error\` opts into strict rejection. \`display_precision\` is a consumer-side rendering hint; the engine never enforces it. Pick per field meaning: identity dates (birthdays, since_date) = \`day\`; event timestamps (opened_at, logged_at) = \`second\` or \`millisecond\`. See \`_skills/schema-guide.md\` for the full contract.
+- Money fields use amount type ("1250.00 USD")
+- Cross-entity links use ref type with target
+- Writes return \`_meta.warnings[]\` when values trip soft-validation (precision drift, etc.). Surface these to the caller instead of silently ignoring — agents should self-correct on warnings, not just on errors.
+
+### Example schema shape (current DSL)
+
+A typical modern schema file (\`_schema/case.v1.yaml\`):
+
+\`\`\`yaml
+type: case
+version: 1
+required: [doc_id, title, client, status]
+fields:
+  title:
+    type: string
+    index: true
+  client:
+    type: ref
+    target: client
+    index: true
+  status:
+    type: enum
+    values: [open, pending, closed]
+    index: true
+  opened_at:
+    type: date
+    store_precision: day        # contract minimum for this field
+    on_coarser: warn            # default; 'error' to reject coarser writes
+    display_precision: day
+    index: true
+  resolved_at:
+    type: date
+    store_precision: second     # events captured at event-moment granularity
+    display_precision: minute   # UIs drop seconds on render
+template:
+  headings:
+    - { level: 1, text: "{{title}}", id: summary }
+    - { level: 2, text: Timeline, id: timeline }
+    - { level: 2, text: Notes, id: notes }
+\`\`\`
+
+Only declare precision hints on date fields where the contract actually matters. Leaving them unset is fully backward-compatible (pre-0.6.7 lenient behavior).
+
+### ID rules (critical — do not skip)
+- \`id_prefix\` in the registry MUST be 2-5 lowercase alphanumeric characters (e.g. \`cli\`, \`usr\`, \`cas\`, \`note\`, \`te\`)
+- Single characters (C, U, N), uppercase (CS, TE), and symbols are rejected
+- MAAD generates its own IDs: \`<prefix>-<sequence>\` (e.g. \`cli-001\`, \`usr-012\`)
+- **Source data IDs are input data, not MAAD IDs.** Do not change the registry to match source IDs. Map source IDs to MAAD format during import (e.g. C001 → cli-001, U005 → usr-005)
+- Store the original source ID in a field (e.g. \`source_id\`) if you need to cross-reference back
+
+## Design Process
+
+Once you have enough information:
+
+### 1. Classify types
+For each entity, determine: master or transaction. Use the >1K/year rule.
+
+### 2. Map relationships
+Draw the refs: what points to what. A job refs a customer and a technician. A note appends to a job.
+
+### 3. Define fields
+For each type: name, type, required, indexed, enum values, ref targets. Use domain knowledge for sensible defaults.
+
+### 4. Estimate volume
+Rough annual record count per type. This validates master vs transaction decisions.
+
+### 5. Present the plan
+Output a clear summary:
+
+\`\`\`
+Proposed MAAD Structure:
+
+Master types (one file per record):
+  - customer: name, phone, email, address, type [residential, commercial], since. ~500/yr
+  - technician: name, phone, certifications, hire_date. ~20 total
+  - job: customer→, technician→, service_type, scheduled, status [scheduled, in_progress, completed, cancelled], amount. ~3000/yr
+
+Transaction types (append to parent file):
+  - job_note: appended to job file. date, author, note text. ~15000/yr
+
+Relationships:
+  job → customer (ref)
+  job → technician (ref)
+  job_note → job (appended to file)
+\`\`\`
+
+If operating agent-to-agent with full spec: skip presentation, build immediately.
+If operating with partial spec or interactively: present and wait for confirmation.
+
+## Build Sequence
+
+After design is confirmed (or in autonomous mode):
+
+1. Write \`_registry/object_types.yaml\` with all types
+2. Write \`_schema/<type>.v1.yaml\` for each type
+3. Call \`maad_reload\` to pick up new config
+4. Call \`maad_summary\` to verify engine loaded the types
+5. Optionally create 1-2 sample records per type to validate the schema
+6. Inspect \`_meta.warnings[]\` on sample-record responses — if intended-coarse values trip precision warnings, tighten the schema or adjust the sample input before proceeding
+7. Call \`maad_reindex\` if sample records were created
+8. Report: "Database deployed. X types, Y fields. Ready for data."
+9. **Register your own identity** as an agent record. Use the existence-check-then-create pattern — do **not** call \`maad_create\` blindly, it will collide on re-runs against an already-bootstrapped project:
+
+   \`\`\`
+   maad_get agt-architect
+     → if not found:
+       maad_create agent {
+         docId: "agt-architect",
+         name: "architect",
+         role: "MAAD Architect — bootstrapped this project's schema",
+         description: "Designed registry + schemas on <ISO date>",
+         status: "active",
+         created_at: <now ISO>
+       }
+     → if already exists:
+       You're re-running against a bootstrapped project. Skip the
+       create; optionally \`maad_update\` to refresh \`description\`
+       if you're reorganizing schemas.
+   \`\`\`
+
+   This persists provenance — queryable later as "which agent bootstrapped this project." Load-bearing once multiple architect instances operate (e.g., hosted deployments where each tenant brain gets its own bootstrap) or when compliance audits need design-time attribution.
+
+## Bulk Data Import
+
+For importing large datasets, use \`maad_bulk_create\` instead of individual creates:
+
+- Accepts an array of records, returns per-record success/failure
+- One bad record doesn't block others
+- Single git commit for all successful records
+- Import parent types first (clients, contacts), then dependent types (cases, notes)
+- For updates, use \`maad_bulk_update\` with the same pattern
+- \`maad_aggregate\` is useful for verifying counts after import
+
+## Troubleshooting
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| reload fails | Registry YAML syntax error | Check YAML formatting, fix, reload again |
+| create fails validation | Field value doesn't match schema | Check \`maad_schema <type>\` for expected types/enums |
+| missing type error | Registry has type but reload wasn't called | Call \`maad_reload\` |
+| search returns too many results | Missing query/value param | Use \`query\` (substring) or \`value\` (exact) param to filter |
+| writes queue under contention | Engine serializes mutating ops via FIFO write mutex (since 0.4.1) | Writes don't fail — they queue. If they hang, check \`maad_health\` for \`writeQueueDepth\` and \`lastWriteOp\`. Still: never issue parallel writes from one caller. |
+| write rejected with \`RATE_LIMITED\` | Session exceeded the per-session token bucket | Honor \`retryAfterMs\` from the error details; use exponential backoff |
+| write response includes \`_meta.warnings[]\` | Value tripped a soft-validation check (e.g. precision coarser than declared) | Write succeeded. Decide whether to re-issue with the declared precision or tighten the schema |
+
+## Handoff
+
+After deployment, report to the requesting agent or user:
+- What types were created
+- How many fields per type
+- Key relationships
+- What MCP tools are available for this structure
+- Any limitations or notes (e.g., "notes are appended to job files, use get warm to read individual notes")
+
+Then transition to MAAD User mode for day-to-day operations, or hand control back to the upstream agent.
+
+## Change Propagation
+
+If the project will involve multiple agents, a hosted deployment, or scheduled workers, point the user at \`docs/change-feed.md\` in the engine repo. Key calls: \`maad_changes_since\` is the polling delta tool (shipped); cursor must be persisted between calls; in HTTP deployments polling belongs in the gateway, not the agent's reasoning loop; push via \`maad_subscribe\` is roadmapped for 0.6.5. Do not invent custom polling cadence in skill files — follow the patterns in the reference doc.
+
+## What MAAD Is and Is Not
+
+**Good fit:**
+- Narrative + structured data (cases, notes, reports, customer records)
+- Relationship-heavy data (who connects to what)
+- Data that needs to be queried AND read in full context
+- LLM-native workflows where agents read/write/search data
+- Audit trail requirements (git-backed, every write tracked)
+
+**Not a fit (yet):**
+- Real-time transactional systems (stock trading, live telemetry)
+- Binary data (images, videos — only metadata refs)
+- >100K writes/day (SQLite single-writer constraint)
+- Multi-tenant SaaS (one project = one tenant currently)
+
+Be honest about limitations when asked. Recommend alternatives when MAAD isn't the right tool.
+`;
+}
+//# sourceMappingURL=architect.js.map

package/dist/architect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"architect.js","sourceRoot":"","sources":["../src/architect.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,2CAA2C;AAC3C,4EAA4E;AAC5E,2DAA2D;AAC3D,+EAA+E;AAE/E,MAAM,UAAU,sBAAsB;IACpC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwQR,CAAC;AACF,CAAC"}

package/dist/auth/resolve.d.ts

@@ -0,0 +1,36 @@
+import type { Role } from '../mcp/roles.js';
+import type { TokenRecord } from './types.js';
+export type CapResolution = {
+    allowed: true;
+    role: Role;
+} | {
+    allowed: false;
+    reason: 'TOKEN_PROJECT_FORBIDDEN';
+};
+/**
+ * Find the per-project role cap for a token. Explicit entry > wildcard >
+ * forbidden. Per-project role downgrades are capped at the token's global
+ * role (lock #4) — an entry that claims higher is silently clamped rather
+ * than rejected, which is safe because the outer three-cap composition will
+ * clamp again against the project ceiling.
+ */
+export declare function resolveTokenCap(token: TokenRecord, projectName: string): CapResolution;
+export type ThreeCapResolution = {
+    ok: true;
+    role: Role;
+} | {
+    ok: false;
+    code: 'TOKEN_PROJECT_FORBIDDEN' | 'ROLE_UPGRADE_DENIED';
+    message: string;
+};
+/**
+ * Three-cap composition. Used in HTTP/registry mode at bind time.
+ *
+ * Returns the lowest of (instance-project ceiling, token cap, requested).
+ * Fails if the token forbids the project, or if the requested role exceeds
+ * what the ceilings allow.
+ *
+ * `requested` of undefined means "whatever the caps give me."
+ */
+export declare function composeEffectiveRole(projectRole: Role, token: TokenRecord, projectName: string, requested?: Role): ThreeCapResolution;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/auth/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/auth/resolve.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,KAAK,EAAE,WAAW,EAAc,MAAM,YAAY,CAAC;AAE1D,MAAM,MAAM,aAAa,GACrB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GAC7B;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,yBAAyB,CAAA;CAAE,CAAC;AAE1D;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,GAAG,aAAa,CAQtF;AAQD,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GACxB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,yBAAyB,GAAG,qBAAqB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5F;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,IAAI,EACjB,KAAK,EAAE,WAAW,EAClB,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,IAAI,GACf,kBAAkB,CAwBpB"}

package/dist/auth/resolve.js

@@ -0,0 +1,77 @@
+// ============================================================================
+// Auth resolution — token → project cap → three-cap effective role
+//
+// Pure functions, no I/O. Composed by SessionRegistry.bindSingle/bindMulti
+// (HTTP + registry mode) and bypassed entirely in stdio/synthetic mode
+// (which has no token channel and uses the two-cap model from 0.4.0).
+//
+// THREE-CAP RULE (dec-maadb-069 lock #7):
+//   effectiveRole(project) = min(
+//     instance.projects[project].role,   // Cap 1: project ceiling
+//     token.cap-for-project,              // Cap 2: token allowlist role
+//     requestedRole                       // Cap 3: voluntary downgrade
+//   )
+//
+// CAP 2 RESOLUTION (dec-maadb-069 lock #4):
+//   1. Explicit entry for the project name wins, regardless of list order.
+//   2. Wildcard '*' entry applies if no explicit entry matches.
+//   3. Otherwise the project is forbidden → TOKEN_PROJECT_FORBIDDEN.
+//   Entries with no `role` field inherit the token's global role; entries
+//   with `role` downgrade to that role (never exceeds global — enforced at
+//   load time would be defensive but lock #4 intent is resolver-side).
+// ============================================================================
+import { minRole, roleSatisfies } from '../mcp/roles.js';
+/**
+ * Find the per-project role cap for a token. Explicit entry > wildcard >
+ * forbidden. Per-project role downgrades are capped at the token's global
+ * role (lock #4) — an entry that claims higher is silently clamped rather
+ * than rejected, which is safe because the outer three-cap composition will
+ * clamp again against the project ceiling.
+ */
+export function resolveTokenCap(token, projectName) {
+    const explicit = token.projects.find(p => p.name === projectName);
+    if (explicit)
+        return { allowed: true, role: capFor(explicit, token.role) };
+    const wildcard = token.projects.find(p => p.name === '*');
+    if (wildcard)
+        return { allowed: true, role: capFor(wildcard, token.role) };
+    return { allowed: false, reason: 'TOKEN_PROJECT_FORBIDDEN' };
+}
+function capFor(entry, tokenGlobalRole) {
+    const requested = entry.role ?? tokenGlobalRole;
+    // Clamp: per-project cap never exceeds the token's global role.
+    return minRole(tokenGlobalRole, requested);
+}
+/**
+ * Three-cap composition. Used in HTTP/registry mode at bind time.
+ *
+ * Returns the lowest of (instance-project ceiling, token cap, requested).
+ * Fails if the token forbids the project, or if the requested role exceeds
+ * what the ceilings allow.
+ *
+ * `requested` of undefined means "whatever the caps give me."
+ */
+export function composeEffectiveRole(projectRole, token, projectName, requested) {
+    const cap = resolveTokenCap(token, projectName);
+    if (!cap.allowed) {
+        return {
+            ok: false,
+            code: 'TOKEN_PROJECT_FORBIDDEN',
+            message: `Token does not allow project "${projectName}"`,
+        };
+    }
+    // Cap 1 × Cap 2: lowest of project ceiling and token cap.
+    const ceiling = minRole(projectRole, cap.role);
+    if (requested === undefined)
+        return { ok: true, role: ceiling };
+    // Cap 3: caller's requested role must be within the ceiling.
+    if (!roleSatisfies(ceiling, requested)) {
+        return {
+            ok: false,
+            code: 'ROLE_UPGRADE_DENIED',
+            message: `Cannot bind as ${requested} — token+project ceiling is ${ceiling}`,
+        };
+    }
+    return { ok: true, role: minRole(ceiling, requested) };
+}
+//# sourceMappingURL=resolve.js.map

package/dist/auth/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../src/auth/resolve.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,mEAAmE;AACnE,EAAE;AACF,2EAA2E;AAC3E,uEAAuE;AACvE,sEAAsE;AACtE,EAAE;AACF,0CAA0C;AAC1C,kCAAkC;AAClC,mEAAmE;AACnE,yEAAyE;AACzE,wEAAwE;AACxE,MAAM;AACN,EAAE;AACF,4CAA4C;AAC5C,2EAA2E;AAC3E,gEAAgE;AAChE,qEAAqE;AACrE,0EAA0E;AAC1E,2EAA2E;AAC3E,uEAAuE;AACvE,+EAA+E;AAG/E,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAOzD;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,KAAkB,EAAE,WAAmB;IACrE,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC;IAClE,IAAI,QAAQ;QAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;IAE3E,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC;IAC1D,IAAI,QAAQ;QAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;IAE3E,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,yBAAyB,EAAE,CAAC;AAC/D,CAAC;AAED,SAAS,MAAM,CAAC,KAAiB,EAAE,eAAqB;IACtD,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,IAAI,eAAe,CAAC;IAChD,gEAAgE;IAChE,OAAO,OAAO,CAAC,eAAe,EAAE,SAAS,CAAC,CAAC;AAC7C,CAAC;AAMD;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAClC,WAAiB,EACjB,KAAkB,EAClB,WAAmB,EACnB,SAAgB;IAEhB,MAAM,GAAG,GAAG,eAAe,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;IAChD,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QACjB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,yBAAyB;YAC/B,OAAO,EAAE,iCAAiC,WAAW,GAAG;SACzD,CAAC;IACJ,CAAC;IAED,0DAA0D;IAC1D,MAAM,OAAO,GAAG,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;IAE/C,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAEhE,6DAA6D;IAC7D,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;QACvC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,qBAAqB;YAC3B,OAAO,EAAE,kBAAkB,SAAS,+BAA+B,OAAO,EAAE;SAC7E,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;AACzD,CAAC"}

package/dist/auth/token-store.d.ts

@@ -0,0 +1,82 @@
+import { type Result } from '../errors.js';
+import { type TokenId, type TokenHash, type TokenRecord, type IssueSpec, type IssuedToken } from './types.js';
+export declare const TOKENS_FILE_RELATIVE: string;
+/**
+ * Generate a new plaintext bearer in the locked format: maad_pat_<32hex>.
+ * Shell-safe (hex only), 128 bits random, prefix visible in logs / scanners.
+ */
+export declare function generatePlaintext(): string;
+/** Plaintext → SHA-256 hex. The sole lookup key that persists. */
+export declare function hashPlaintext(plaintext: string): TokenHash;
+/** Format check — cheap defensive filter before hashing arbitrary bearers. */
+export declare function looksLikeToken(bearer: string): boolean;
+export declare class TokenStore {
+    private filePath;
+    private registryName;
+    private byHash;
+    private byId;
+    private records;
+    private constructor();
+    /**
+     * Load tokens.yaml from `<instanceRoot>/_auth/tokens.yaml`. Returns an empty
+     * store if the file is absent — caller decides whether HTTP mode can boot
+     * against that state (the HTTP boot-mode matrix in the 0.7.0 spec).
+     *
+     * Parse errors are NOT silent: TOKENS_FILE_INVALID is returned with the
+     * file path + js-yaml message so operators can fix the file without
+     * guessing.
+     */
+    static load(instanceRoot: string): Promise<Result<TokenStore>>;
+    /** Absolute path to the backing file. */
+    path(): string;
+    /**
+     * 0.7.0 — Re-read tokens.yaml from disk and swap the in-memory indexes
+     * in-place. Captures of the TokenStore reference stay valid (so the HTTP
+     * transport doesn't need a getter). Parse errors leave the existing
+     * in-memory state untouched. Called by the SIGHUP handler alongside
+     * instance reload.
+     */
+    reload(): Promise<Result<{
+        total: number;
+        active: number;
+    }>>;
+    /** Optional human label recorded at the top of tokens.yaml. */
+    name(): string | undefined;
+    /** Total records including revoked. */
+    size(): number;
+    /** Records with no revokedAt and no expiresAt-in-the-past. */
+    activeCount(now?: Date): number;
+    /** O(1) lookup by hash. Returns undefined for unknown bearers. */
+    lookupByHash(hash: TokenHash): TokenRecord | undefined;
+    /** Secondary lookup by readable id (CLI / admin paths). */
+    lookupById(id: TokenId): TokenRecord | undefined;
+    /** Snapshot of all records. Caller receives a shallow copy. */
+    list(): TokenRecord[];
+    /**
+     * Issue a new token. Generates plaintext + hash, appends the record,
+     * persists the file atomically. Returns both the record and the plaintext —
+     * plaintext is never recoverable after this call.
+     */
+    issue(spec: IssueSpec): Promise<Result<IssuedToken>>;
+    /**
+     * Mark a token as revoked. Sets revokedAt; the record stays in the registry
+     * so audit queries can resolve historic token IDs. Idempotent — revoking
+     * an already-revoked record is a no-op and returns the existing record.
+     */
+    revoke(id: TokenId): Promise<Result<TokenRecord>>;
+    /**
+     * Rotate a token: issue a new token with the SAME capabilities (role,
+     * projects, agentId, userId, expiresAt, name) and revoke the old one.
+     * Immediate cutover — no grace window (deferred per dec-maadb-069 lock #10).
+     * Returns the new record + plaintext; old record retains its id with
+     * revokedAt set.
+     */
+    rotate(id: TokenId): Promise<Result<IssuedToken>>;
+    /**
+     * Atomic write via `<path>.tmp` + rename. Creates `_auth/` if missing.
+     * Errors don't leak partial state because writeFile+rename is atomic on
+     * both POSIX and Windows.
+     */
+    private persist;
+}
+//# sourceMappingURL=token-store.d.ts.map

package/dist/auth/token-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-store.d.ts","sourceRoot":"","sources":["../../src/auth/token-store.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAiB,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAGL,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,WAAW,EAGjB,MAAM,YAAY,CAAC;AAMpB,eAAO,MAAM,oBAAoB,QAAoC,CAAC;AAEtE;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAG1C;AAED,kEAAkE;AAClE,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAE1D;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAItD;AAMD,qBAAa,UAAU;IAMnB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,YAAY;IANtB,OAAO,CAAC,MAAM,CAAqC;IACnD,OAAO,CAAC,IAAI,CAAmC;IAC/C,OAAO,CAAC,OAAO,CAAqB;IAEpC,OAAO;IAKP;;;;;;;;OAQG;WACU,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAmCpE,yCAAyC;IACzC,IAAI,IAAI,MAAM;IAEd;;;;;;OAMG;IACG,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IA0ClE,+DAA+D;IAC/D,IAAI,IAAI,MAAM,GAAG,SAAS;IAE1B,uCAAuC;IACvC,IAAI,IAAI,MAAM;IAEd,8DAA8D;IAC9D,WAAW,CAAC,GAAG,GAAE,IAAiB,GAAG,MAAM;IAM3C,kEAAkE;IAClE,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS;IAItD,2DAA2D;IAC3D,UAAU,CAAC,EAAE,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS;IAIhD,+DAA+D;IAC/D,IAAI,IAAI,WAAW,EAAE;IAErB;;;;OAIG;IACG,KAAK,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAsC1D;;;;OAIG;IACG,MAAM,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAcvD;;;;;;OAMG;IACG,MAAM,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAiCvD;;;;OAIG;YACW,OAAO;CA4BtB"}