@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.7

package/packages/agentsam-rapid-rust/templates/api/Cargo.toml.tmpl

@@ -0,0 +1,18 @@
+[package]
+name = "{{PROJECT_NAME}}"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+worker = "{{WORKER_VERSION}}"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+
+[profile.release]
+lto = true
+strip = "debuginfo"
+codegen-units = 1
+opt-level = "s"

package/packages/agentsam-rapid-rust/templates/api/src/lib.rs.tmpl

@@ -0,0 +1,17 @@
+use serde_json::json;
+use worker::*;
+
+#[event(fetch)]
+pub async fn main(req: Request, env: Env, _ctx: Context) -> Result<Response> {
+    Router::new()
+        .get("/", |_req, _ctx| Response::ok("AgentSam Rust/Wasm Worker"))
+        .get("/health", |_req, _ctx| {
+            Response::from_json(&json!({
+                "status": "ok",
+                "runtime": "cloudflare-workers-rust-wasm",
+                "project": "{{PROJECT_NAME}}"
+            }))
+        })
+        .run(req, env)
+        .await
+}

package/packages/agentsam-rapid-rust/templates/common/README.md.tmpl

@@ -0,0 +1,22 @@
+# {{PROJECT_NAME}}
+
+AgentSam Rapid Rust template: `{{TEMPLATE}}`.
+
+## Local first
+
+```bash
+npm install
+agentsam rust doctor --bootstrap
+agentsam rust check
+agentsam rust build
+agentsam rust dev
+```
+
+## Explicit cloud graduation
+
+```bash
+agentsam rust deploy --dry-run
+agentsam rust deploy --yes
+```
+
+No scaffold/build/check command deploys this Worker.

package/packages/agentsam-rapid-rust/templates/common/package.json.tmpl

@@ -0,0 +1,12 @@
+{
+  "name": "{{PROJECT_NAME}}-worker",
+  "private": true,
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "deploy:dry": "wrangler deploy --dry-run"
+  },
+  "devDependencies": {
+    "wrangler": "{{WRANGLER_VERSION}}"
+  }
+}

package/packages/agentsam-rapid-rust/templates/common/wrangler.toml.tmpl

@@ -0,0 +1,6 @@
+name = "{{PROJECT_NAME}}"
+main = "build/index.js"
+compatibility_date = "{{COMPATIBILITY_DATE}}"
+
+[build]
+command = "worker-build --release"

package/packages/agentsam-rapid-rust/templates/crypto-auth/Cargo.toml.tmpl

@@ -0,0 +1,21 @@
+[package]
+name = "{{PROJECT_NAME}}"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+worker = "{{WORKER_VERSION}}"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+hmac = "0.12"
+sha2 = "0.10"
+hex = "0.4"
+
+[profile.release]
+lto = true
+strip = "debuginfo"
+codegen-units = 1
+opt-level = "s"

package/packages/agentsam-rapid-rust/templates/crypto-auth/src/lib.rs.tmpl

@@ -0,0 +1,32 @@
+use hmac::{Hmac, Mac};
+use sha2::Sha256;
+use worker::*;
+
+type HmacSha256 = Hmac<Sha256>;
+
+#[event(fetch)]
+pub async fn main(req: Request, env: Env, _ctx: Context) -> Result<Response> {
+    Router::new()
+        .post_async("/verify-signature", |mut req, ctx| async move {
+            let secret = ctx.secret("API_SECRET")?.to_string();
+            let provided = match req.headers().get("X-Signature")? {
+                Some(value) => value,
+                None => return Response::error("missing X-Signature", 401),
+            };
+            let provided = match hex::decode(provided.trim()) {
+                Ok(value) => value,
+                Err(_) => return Response::error("invalid signature encoding", 400),
+            };
+            let payload = req.bytes().await?;
+            let mut mac = HmacSha256::new_from_slice(secret.as_bytes())
+                .map_err(|_| Error::RustError("invalid HMAC key".into()))?;
+            mac.update(&payload);
+            if mac.verify_slice(&provided).is_ok() {
+                Response::ok("signature valid")
+            } else {
+                Response::error("invalid signature", 403)
+            }
+        })
+        .run(req, env)
+        .await
+}

package/packages/agentsam-rapid-rust/templates/data-processor/Cargo.toml.tmpl

@@ -0,0 +1,18 @@
+[package]
+name = "{{PROJECT_NAME}}"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+worker = "{{WORKER_VERSION}}"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+
+[profile.release]
+lto = true
+strip = "debuginfo"
+codegen-units = 1
+opt-level = "s"

package/packages/agentsam-rapid-rust/templates/data-processor/src/lib.rs.tmpl

@@ -0,0 +1,41 @@
+use serde::{Deserialize, Serialize};
+use worker::*;
+
+#[derive(Debug, Deserialize, Serialize)]
+struct BatchInput {
+    items: Vec<RawItem>,
+}
+
+#[derive(Debug, Deserialize, Serialize)]
+struct RawItem {
+    id: u64,
+    value: f64,
+}
+
+#[derive(Serialize)]
+struct BatchResult {
+    processed_count: usize,
+    total_sum: f64,
+    average: f64,
+}
+
+#[event(fetch)]
+pub async fn main(req: Request, env: Env, _ctx: Context) -> Result<Response> {
+    Router::new()
+        .post_async("/process", |mut req, _ctx| async move {
+            let data: BatchInput = match req.json().await {
+                Ok(value) => value,
+                Err(_) => return Response::error("invalid JSON payload", 400),
+            };
+            let count = data.items.len();
+            let sum: f64 = data.items.iter().map(|item| item.value).sum();
+            let average = if count == 0 { 0.0 } else { sum / count as f64 };
+            Response::from_json(&BatchResult {
+                processed_count: count,
+                total_sum: sum,
+                average,
+            })
+        })
+        .run(req, env)
+        .await
+}

package/packages/agentsam-rapid-rust/templates/shared-core/Cargo.toml.tmpl

@@ -0,0 +1,9 @@
+[workspace]
+members = ["core", "worker"]
+resolver = "2"
+
+[profile.release]
+lto = true
+strip = "debuginfo"
+codegen-units = 1
+opt-level = "s"

package/packages/agentsam-rapid-rust/templates/shared-core/core/Cargo.toml.tmpl

@@ -0,0 +1,7 @@
+[package]
+name = "{{PROJECT_NAME}}-core"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+crate-type = ["rlib"]

package/packages/agentsam-rapid-rust/templates/shared-core/core/src/lib.rs.tmpl

@@ -0,0 +1,23 @@
+/// Pure Rust domain logic: no Cloudflare, browser, or Tauri dependency.
+pub fn normalize_resource_key(input: &str) -> String {
+    input
+        .trim()
+        .to_ascii_lowercase()
+        .chars()
+        .map(|ch| if ch.is_ascii_alphanumeric() { ch } else { '-' })
+        .collect::<String>()
+        .split('-')
+        .filter(|part| !part.is_empty())
+        .collect::<Vec<_>>()
+        .join("-")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn normalizes_keys_deterministically() {
+        assert_eq!(normalize_resource_key("  Hello / World  "), "hello-world");
+    }
+}

package/packages/agentsam-rapid-rust/templates/shared-core/worker/Cargo.toml.tmpl

@@ -0,0 +1,12 @@
+[package]
+name = "{{PROJECT_NAME}}-worker"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+shared_core = { package = "{{PROJECT_NAME}}-core", path = "../core" }
+worker = "{{WORKER_VERSION}}"
+serde_json = "1.0"

package/packages/agentsam-rapid-rust/templates/shared-core/worker/src/lib.rs.tmpl

@@ -0,0 +1,16 @@
+use serde_json::json;
+use worker::*;
+
+#[event(fetch)]
+pub async fn main(req: Request, env: Env, _ctx: Context) -> Result<Response> {
+    Router::new()
+        .get("/normalize/:value", |_req, ctx| {
+            let value = ctx.param("value").map(String::as_str).unwrap_or("");
+            Response::from_json(&json!({
+                "input": value,
+                "normalized": shared_core::normalize_resource_key(value)
+            }))
+        })
+        .run(req, env)
+        .await
+}

package/packages/agentsam-rapid-rust/templates/shared-core/wrangler.toml.tmpl

@@ -0,0 +1,6 @@
+name = "{{PROJECT_NAME}}"
+main = "worker/build/index.js"
+compatibility_date = "{{COMPATIBILITY_DATE}}"
+
+[build]
+command = "cd worker && worker-build --release"

package/packages/agentsam-repository/package.json

@@ -1,7 +1,6 @@
 {
   "name": "@inneranimalmedia/agentsam-repository",
-  "version": "0.1.0",
-  "private": true,
+  "version": "2.6.7",
   "description": "Portable AgentSam repository identity, Merkle, semantic file metadata, persistence, and repository graph runtime contracts.",
   "type": "module",
   "main": "./src/index.js",
@@ -21,5 +20,16 @@
   },
   "engines": {
     "node": ">=22 <25"
-  }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SamPrimeaux/agentsam-sdk.git",
+    "directory": "packages/agentsam-repository"
+  },
+  "files": [
+    "src"
+  ]
 }

package/packages/agentsam-repository/src/index.js

@@ -1,4 +1,5 @@
 export { resolveGitContext, tryResolveGitContext, normalizeGitRemote } from './git-context.js';
+export * from './source-types.js';
 export * from './contracts.js';
 export * from './merkle/index.js';
 export * from './work-tracking.js';

package/packages/agentsam-repository/src/merkle/semantic.js

@@ -3,16 +3,9 @@ import path from 'node:path';
 import ts from 'typescript';
 import { comparePaths, fileHasher } from './hash.js';
 import { FILEMETA_FORMAT, FILEMETA_VERSION, metadataRoot } from './filemeta.js';
+import { isAstSourceExtension, sourceLanguageIdForExtension } from '../source-types.js';
 const MAX_AST_BYTES = 2 * 1024 * 1024;
 
-const LANGUAGE_BY_EXTENSION = Object.freeze({
-  '.c': 'c', '.cc': 'cpp', '.cpp': 'cpp', '.cxx': 'cpp', '.css': 'css', '.go': 'go',
-  '.h': 'c', '.hpp': 'cpp', '.html': 'html', '.java': 'java', '.js': 'javascript',
-  '.jsx': 'javascript', '.json': 'json', '.md': 'markdown', '.mjs': 'javascript',
-  '.cjs': 'javascript', '.py': 'python', '.rs': 'rust', '.scss': 'scss', '.sql': 'sql',
-  '.ts': 'typescript', '.tsx': 'typescript', '.yaml': 'yaml', '.yml': 'yaml',
-});
-const AST_EXTENSIONS = new Set(['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx']);
 const ASSET_EXTENSIONS = new Set([
   '.avif', '.eot', '.gif', '.ico', '.jpeg', '.jpg', '.mp3', '.mp4', '.ogg', '.otf', '.pdf',
   '.png', '.svg', '.ttf', '.wav', '.webm', '.webp', '.woff', '.woff2',
@@ -305,7 +298,7 @@ export async function buildSemanticMetadata(rootPath, tree) {
     const pkg = nearestPackage(contentEntry.path, packages);
     const localPath = pkg?.root && contentEntry.path.startsWith(pkg.root + '/') ? contentEntry.path.slice(pkg.root.length + 1) : contentEntry.path;
     const ext = extensionOf(contentEntry.path);
-    const language = LANGUAGE_BY_EXTENSION[ext] || null;
+    const language = sourceLanguageIdForExtension(ext);
     const layer = inferLayer(contentEntry.path, pkg?.root || '');
     const kind = contentEntry.type === 'symlink' ? 'symlink' : inferKind(contentEntry.path, language);
     const structuralSystem = (contentEntry.path.startsWith('packages/') || contentEntry.path.startsWith('apps/')) ? contentEntry.path.split('/')[1] : null;
@@ -314,7 +307,7 @@ export async function buildSemanticMetadata(rootPath, tree) {
     const tags = new Set([...(Array.isArray(pkg?.agentsam?.tags) ? pkg.agentsam.tags : []), ...(explicit.tags || [])].filter((tag) => typeof tag === 'string' && tag));
     let mode = contentEntry.mode;
     let sourceBuffer = null;
-    if (contentEntry.type === 'file' && AST_EXTENSIONS.has(ext) && contentEntry.size <= MAX_AST_BYTES) {
+    if (contentEntry.type === 'file' && isAstSourceExtension(ext) && contentEntry.size <= MAX_AST_BYTES) {
       const verified = await readVerifiedFile(rootPath, contentEntry);
       if (mode != null && verified.mode !== mode) throw new Error(`File mode changed while building semantic metadata: ${contentEntry.path}`);
       mode = verified.mode;

package/packages/agentsam-repository/src/source-types.js

@@ -0,0 +1,93 @@
+/**
+ * Source-type helpers for AgentSam repository intelligence.
+ *
+ * SSOT taxonomy (extensions / kind / ast / knowledge):
+ *   contracts/source-types.v1.json
+ * Rust machine inspect loads the same contract. Keep this JS table aligned when
+ * adding languages until a shared loader is wired for both runtimes.
+ */
+import path from 'node:path';
+
+const DEFINITIONS = [
+  { id: 'javascript', label: 'JavaScript', kind: 'code', extensions: ['.js', '.mjs', '.cjs', '.jsx'], knowledge: true, ast: true },
+  { id: 'typescript', label: 'TypeScript', kind: 'code', extensions: ['.ts', '.tsx'], knowledge: true, ast: true },
+  { id: 'rust', label: 'Rust', kind: 'code', extensions: ['.rs'], knowledge: true },
+  { id: 'python', label: 'Python', kind: 'code', extensions: ['.py'], knowledge: true },
+  { id: 'go', label: 'Go', kind: 'code', extensions: ['.go'], knowledge: true },
+  { id: 'java', label: 'Java', kind: 'code', extensions: ['.java'] },
+  { id: 'kotlin', label: 'Kotlin', kind: 'code', extensions: ['.kt'] },
+  { id: 'swift', label: 'Swift', kind: 'code', extensions: ['.swift'] },
+  { id: 'c', label: 'C', kind: 'code', extensions: ['.c', '.h'] },
+  { id: 'cpp', label: 'C++', kind: 'code', extensions: ['.cc', '.cpp', '.cxx', '.hpp'] },
+  { id: 'csharp', label: 'C#', kind: 'code', extensions: ['.cs'] },
+  { id: 'ruby', label: 'Ruby', kind: 'code', extensions: ['.rb'] },
+  { id: 'php', label: 'PHP', kind: 'code', extensions: ['.php'] },
+  { id: 'sql', label: 'SQL', kind: 'code', extensions: ['.sql'], knowledge: true },
+  { id: 'shell', label: 'Shell', kind: 'code', extensions: ['.sh', '.bash', '.zsh'] },
+  { id: 'yaml', label: 'YAML', kind: 'code', extensions: ['.yaml', '.yml'] },
+  { id: 'toml', label: 'TOML', kind: 'code', extensions: ['.toml'] },
+  { id: 'vue', label: 'Vue', kind: 'code', extensions: ['.vue'] },
+  { id: 'svelte', label: 'Svelte', kind: 'code', extensions: ['.svelte'] },
+  { id: 'markdown', label: 'Markdown', kind: 'document', extensions: ['.md', '.mdx'], knowledge: true },
+  { id: 'json', label: 'JSON', kind: 'document', extensions: ['.json'], knowledge: true },
+  { id: 'html', label: 'HTML', kind: 'document', extensions: ['.html', '.htm'] },
+  { id: 'css', label: 'CSS', kind: 'document', extensions: ['.css', '.scss'] },
+  { id: 'text', label: 'Text', kind: 'document', extensions: ['.txt'] },
+  { id: 'xml', label: 'XML', kind: 'document', extensions: ['.xml'] },
+  { id: 'csv', label: 'CSV', kind: 'document', extensions: ['.csv'] },
+];
+
+export const SOURCE_TYPES = Object.freeze(
+  DEFINITIONS.map((definition) => Object.freeze({
+    ...definition,
+    extensions: Object.freeze([...definition.extensions]),
+  })),
+);
+
+const BY_EXTENSION = new Map(
+  SOURCE_TYPES.flatMap((definition) => definition.extensions.map((extension) => [extension, definition])),
+);
+
+export function normalizeSourceExtension(value) {
+  const raw = String(value || '').trim().toLowerCase();
+  if (!raw) return '';
+  return raw.startsWith('.') ? raw : '.' + raw;
+}
+
+export function sourceTypeForExtension(value) {
+  return BY_EXTENSION.get(normalizeSourceExtension(value)) || null;
+}
+
+export function sourceTypeForPath(filePath) {
+  const lower = String(filePath || '').toLowerCase();
+  if (lower.endsWith('.d.ts')) return sourceTypeForExtension('.ts');
+  return sourceTypeForExtension(path.posix.extname(lower));
+}
+
+export function sourceLanguageForExtension(value) {
+  return sourceTypeForExtension(value)?.label || null;
+}
+
+export function sourceLanguageIdForExtension(value) {
+  return sourceTypeForExtension(value)?.id || null;
+}
+
+export function isCodeSourceExtension(value) {
+  return sourceTypeForExtension(value)?.kind === 'code';
+}
+
+export function isDocumentSourceExtension(value) {
+  return sourceTypeForExtension(value)?.kind === 'document';
+}
+
+export function isKnowledgeSourceExtension(value) {
+  return sourceTypeForExtension(value)?.knowledge === true;
+}
+
+export function isKnowledgeSourcePath(filePath) {
+  return sourceTypeForPath(filePath)?.knowledge === true;
+}
+
+export function isAstSourceExtension(value) {
+  return sourceTypeForExtension(value)?.ast === true;
+}

package/packages/agentsam-vault/README.md

@@ -0,0 +1,96 @@
+# AgentSam Credential System
+
+## Answers (current Worker)
+
+### How does `/api/vault/*` work?
+
+```
+Browser /settings/keys
+        │
+        ▼
+POST /api/vault/secrets  { service_name, value }
+        │
+        ▼
+AES-256-GCM encrypt with VAULT_MASTER_KEY
+  AAD = userId:service:name
+        │
+        ▼
+D1 user_secrets (ciphertext + metadata + last4)
+        │
+GET list → metadata only (never plaintext)
+POST unwrap → service lane only (bridge / internal)
+```
+
+Auth lanes on the vault Worker:
+
+| Lane | Header / cookie | Use |
+|---|---|---|
+| Browser session | identity session cookie | user manages own BYOK keys |
+| Bridge | `AGENTSAM_BRIDGE_KEY` | machine unwrap / inventory |
+
+## VAULT_MASTER_KEY format
+
+Required:
+
+```
+v1.<base64 of exactly 32 bytes>
+```
+
+Generate / rotate:
+
+```bash
+node -e "import('node:crypto').then(({randomBytes})=>console.log('v1.'+randomBytes(32).toString('base64')))" \
+  | npx wrangler secret put VAULT_MASTER_KEY -c apps/local-studio/backend/wrangler.jsonc
+```
+
+Or: `node apps/local-studio/scripts/ensure-vault-secret.mjs` (mints `v1.` when missing; does **not** rotate an existing secret).
+
+Arbitrary strings are **rejected** (no silent truncate/hash).
+
+### App-owned keys (no cross-app coupling)
+
+Each Worker owns its own `VAULT_MASTER_KEY`. Rotating Local Studio (`agentsam-sdk` Worker via `apps/local-studio/backend/wrangler.jsonc`) has **zero** effect on Inner Animal Media’s Worker secret of the same name, and vice versa. Never copy a vault master key between apps.
+
+### After rotation — BYOK re-save
+
+Existing `user_secrets` ciphertext encrypted under the previous master key will not decrypt. There is no safe server-side re-encrypt without plaintext.
+
+Operational plan:
+
+1. Rotate `VAULT_MASTER_KEY` on the target Worker only (pipe into `wrangler secret put`; never log/print the value).
+2. Deploy that Worker so runtime imports the new `v1.` key.
+3. In Local Studio → **Settings → Keys**, delete orphaned provider rows (or they will fail on unwrap), then re-enter each BYOK value and save. New ciphertext is sealed under the new key.
+4. Do **not** bulk-wipe shared D1 `user_secrets` unless you intend to invalidate every consumer of that table — scope cleanup to the users/services you manage in this app.
+
+### Where is `AGENTSAM_API_KEY` minted / used?
+
+| Concern | Detail |
+|---|---|
+| Format | `aak_*` |
+| Store | IAM D1 `agentsam_api_credentials` (**hash only**) |
+| Verify | `resolveAgentsamApiCredential` on inneranimalmedia |
+| Consume | `Authorization: Bearer aak_…` in SDK/CLI for remote control-plane |
+| Env | Customer sets `AGENTSAM_API_KEY` in wrangler/env — **compatibility adapter**, not primary UX |
+| Not | Browser OAuth session, bridge key, or vault ciphertext |
+
+Mint path: account credential rows are verified today; product mint UI belongs on `/settings/keys` under kind `agentsam_api_key` (registry already defines the provider). Hash insert against `agentsam_api_credentials` is the IAM-side write still to productize.
+
+## New packages (this change)
+
+```
+packages/agentsam-vault/        contracts, AES-GCM, provider registry, resolver
+packages/agentsam-key-manager/  SensitiveInput, KeysPage, IntegrationsPage
+```
+
+Local Studio `/settings/keys` and `/settings/integrations` now consume key-manager; vault API remains the hosted backend.
+
+## Authority split (from your CF dashboard)
+
+| Secret / var | Role |
+|---|---|
+| `VAULT_MASTER_KEY` | Encrypt user_secrets |
+| `AGENTSAM_BRIDGE_KEY` | Machine service auth |
+| `IAM_CLIENT_ID` / `IAM_CLIENT_SECRET` | Hosted OAuth confidential client |
+| `CLOUDFLARE_OAUTH_CLIENT_ID` (+ optional secret) | CF OAuth (PKCE-only OK without secret) |
+| `OPENAI_API_KEY` etc. | Env fallback until vault wins |
+| `AGENTSAM_API_KEY` | Delegated `aak_*` for customers' Workers |

package/packages/agentsam-vault/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@inneranimalmedia/agentsam-vault",
+  "version": "2.6.7",
+  "type": "module",
+  "description": "AgentSam credential vault core — contracts, AES-GCM crypto, provider registry, resolver. UI lives in agentsam-key-manager.",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./contracts": {
+      "types": "./src/contracts/credential.d.ts",
+      "default": "./src/contracts/credential.js"
+    },
+    "./providers": "./src/providers/registry.js",
+    "./crypto": {
+      "types": "./src/crypto/aes-gcm.d.ts",
+      "default": "./src/crypto/aes-gcm.js"
+    },
+    "./resolver": "./src/runtime/resolver.js",
+    "./oauth": "./src/crypto/oauth-envelope.js"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SamPrimeaux/agentsam-sdk.git",
+    "directory": "packages/agentsam-vault"
+  },
+  "files": [
+    "src"
+  ]
+}

package/packages/agentsam-vault/src/contracts/credential.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Portable AgentSam credential / vault contracts (types).
+ * Secrets never live on CredentialRecord — only credential_ref.
+ */
+
+export type CredentialOwnerType = "user" | "account" | "app";
+export type CredentialKind =
+  | "provider_api_key"
+  | "oauth_connection"
+  | "agentsam_api_key"
+  | "app_secret";
+export type CredentialStatus = "active" | "expired" | "revoked" | "invalid";
+
+export interface CredentialRecord {
+  id: string;
+  owner_type: CredentialOwnerType;
+  owner_id: string;
+  kind: CredentialKind;
+  provider?: string;
+  label: string;
+  credential_ref: string;
+  status: CredentialStatus;
+  capabilities?: string[];
+  granted_scopes?: string[];
+  expires_at?: string | null;
+  validated_at?: string | null;
+  last_used_at?: string | null;
+  rotated_at?: string | null;
+  last4?: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface CredentialProviderField {
+  id: string;
+  type: "secret" | "text" | "url";
+  required?: boolean;
+  label?: string;
+}
+
+export interface CredentialProviderDefinition {
+  id: string;
+  label: string;
+  credential: { kind: CredentialKind; sensitive?: boolean };
+  fields: CredentialProviderField[];
+  capabilities?: string[];
+  operations?: { test?: boolean; rotate?: boolean; revoke?: boolean };
+}
+
+export declare const CREDENTIAL_KINDS: Readonly<{
+  PROVIDER_API_KEY: "provider_api_key";
+  OAUTH_CONNECTION: "oauth_connection";
+  AGENTSAM_API_KEY: "agentsam_api_key";
+  APP_SECRET: "app_secret";
+}>;
+
+export declare const CREDENTIAL_STATUSES: Readonly<{
+  ACTIVE: "active";
+  EXPIRED: "expired";
+  REVOKED: "revoked";
+  INVALID: "invalid";
+}>;
+
+export declare const CREDENTIAL_AUTHORITY: Readonly<{
+  vaultMasterKey: "VAULT_MASTER_KEY";
+  agentsamApiKey: "AGENTSAM_API_KEY";
+  agentsamApiKeyPrefix: "aak_";
+  agentsamApiKeyStore: "agentsam_api_credentials";
+  bridgeKey: "AGENTSAM_BRIDGE_KEY";
+}>;
+
+export function normalizeCredentialRecord(
+  input: Partial<CredentialRecord> & Record<string, unknown>,
+): CredentialRecord;
+
+export function defineCredentialProvider(
+  def: CredentialProviderDefinition,
+): CredentialProviderDefinition;