@skyhighmedia/byok-vault 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SkyHighMedia
+
+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.

package/README.md

@@ -0,0 +1,108 @@
+# @skyhighmedia/byok-vault
+
+[![CI](https://github.com/Genesisapps11/byok-vault/actions/workflows/ci.yml/badge.svg)](https://github.com/Genesisapps11/byok-vault/actions/workflows/ci.yml)
+
+**The BYOK vault module SkyHighMedia apps use to keep your provider API key safe — the actual code that does it.**
+
+These apps are BYOK: you bring your own provider API key (e.g. your voice-AI key for
+[SpeakOS](https://speakos.ai)). That key is powerful, so here is *exactly* how it is stored
+and used. This is the real vault module from the products — open so anyone can verify the
+claims below.
+
+**Used by:** [SpeakOS](https://speakos.ai) _(and other SkyHighMedia apps)_.
+
+---
+
+## In plain English
+
+- Your key is **locked in a vault** (encrypted). What sits in the database is scrambled
+  text — the unlock key is held by the database provider, **outside** the data, so a stolen
+  database dump is useless on its own.
+- It is **only ever unlocked on the server, for the moment it is needed**, and never
+  shown to anyone — not other customers, not even to you through the app.
+- It is **never logged by the vault**, which also ships a redaction helper to scrub
+  key-shaped tokens from the app's other logging paths.
+- **You hold the off switch.** It's *your* account — revoke the key anytime from your own
+  provider dashboard and the app instantly has nothing.
+
+## The honest part (read this)
+
+Open-sourcing this code proves our **design and intent**. It does **not** cryptographically
+prove our servers run exactly this code — no amount of publishing can prove that. Concretely,
+the real boundary is **custody of the server-side `service_role` key plus the SQL grants**:
+whoever holds that key can decrypt a stored key server-side, so the guarantee can't rest on any
+single line of app code. That's why the real, structural guarantee isn't our promise: it's
+**BYOK**. You own the account, you see your own billing, and you can kill the key in one click.
+The code below shows we built the careful version; BYOK means you never have to take our word for it.
+
+---
+
+## How it works (technical)
+
+1. **Encrypted at rest — Supabase Vault.** Keys are stored as Vault secrets (`sql/vault.sql`).
+   The ciphertext lives in `vault.secrets`; the encryption key is managed by Supabase outside
+   the database. A `pg_dump` yields ciphertext only.
+2. **Plaintext is `service_role`-only.** Two `SECURITY DEFINER` functions (`store_org_key`,
+   `get_org_key`) are the *only* way to reach a key. `EXECUTE` is **revoked from
+   `anon`/`authenticated`** and granted to `service_role` alone — so a logged-in customer
+   literally cannot call them, and the `vault` schema is never granted to tenant roles.
+3. **Row-Level Security.** A customer can read only their own metadata row — provider +
+   **last 4 characters**, never the key, never another tenant's.
+4. **No-log redaction** (`src/redact.ts`) scrubs key-shaped tokens from values the app
+   passes through it; the vault's own errors carry codes, never key material.
+5. **One chokepoint.** All *app-side* key handling lives in `src/keys.ts`. The boundary that
+   actually *enforces* this is the `service_role`-only SQL functions (#2) plus custody of the
+   service-role key — the TS file is the convention; the SQL grants are the enforcement.
+
+## Install
+
+```bash
+pnpm add @skyhighmedia/byok-vault
+# or: npm install @skyhighmedia/byok-vault
+```
+
+```ts
+import { storeProviderKey, getProviderKey } from '@skyhighmedia/byok-vault'
+import { redactSecrets } from '@skyhighmedia/byok-vault/redact'
+```
+
+> **ESM-only** (Node 18+). Import via ESM; there is no CommonJS `require()` build.
+
+The chokepoint reads `SUPABASE_URL` (or `NEXT_PUBLIC_SUPABASE_URL`) and
+`SUPABASE_SERVICE_ROLE_KEY` from the environment. **Server-only:** the service-role key
+bypasses RLS — never bundle it to a browser. In Next.js, re-export from a module that begins
+with `import 'server-only'`.
+
+## What's in here
+
+| Path | What |
+|---|---|
+| `src/keys.ts` | the store / decrypt-at-call chokepoint |
+| `src/redact.ts` | the no-log redaction layer |
+| `sql/vault.sql` | the vault schema: `org_keys`, the `service_role`-only functions, grants, RLS |
+| `sql/context.sql` | minimal tenancy fixture `vault.sql` builds on (test-only; apps bring their own) |
+| `test/keys.test.ts` | proves: round-trip, ciphertext-only storage, tenant role denied |
+
+## Adopting it in your own schema
+
+`sql/vault.sql` ships with the SpeakOS tenancy as the default. It is parameterised by two
+**HOST SCHEMA CONTRACT** points (documented at the top of the file): the tenant table the key
+rows reference, and the metadata-read RLS predicate. Substitute your own (e.g. `tenants` + a
+JWT-claim predicate) in your app's migration. **Keep the function names and param names
+(`store_org_key` / `get_org_key`, `p_org_id`) unchanged** — the shared `src/keys.ts` calls
+them by name, so keeping them is what lets every app use this package's chokepoint as-is.
+
+## Verify it yourself
+
+```bash
+# 1. create a Supabase project, then apply the schema:
+psql "$DATABASE_URL" -f sql/context.sql -f sql/vault.sql
+# 2. set SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, DATABASE_URL in .env
+pnpm install && pnpm test
+```
+
+The tests are the proof — and they run in CI on every push (see the badge above).
+
+## License
+
+MIT — see [LICENSE](./LICENSE). Part of the SkyHighMedia ecosystem · [speakos.ai](https://speakos.ai)

package/dist/keys.d.ts

@@ -0,0 +1,2 @@
+export declare function storeProviderKey(orgId: string, key: string, provider?: string): Promise<void>;
+export declare function getProviderKey(orgId: string, provider?: string): Promise<string | null>;

package/dist/keys.js

@@ -0,0 +1,39 @@
+import { createClient } from '@supabase/supabase-js';
+// ─────────────────────────────────────────────────────────────────────────────
+// THE single chokepoint for provider-key plaintext.
+// Keys are encrypted in Supabase Vault and only ever read here, server-side,
+// via service_role-only SQL functions. Errors NEVER include key material.
+//
+// SERVER-ONLY: SUPABASE_SERVICE_ROLE_KEY bypasses RLS — never ship it to a
+// browser. This module is framework-agnostic (no hard `import 'server-only'`);
+// re-add that guard in your app's wrapper if your framework supports it.
+// ─────────────────────────────────────────────────────────────────────────────
+const DEFAULT_PROVIDER = 'vapi';
+function adminClient() {
+    // SUPABASE_URL is the canonical name; NEXT_PUBLIC_SUPABASE_URL is accepted as a
+    // fallback so Next.js apps don't need to duplicate the (non-secret) URL.
+    const url = process.env.SUPABASE_URL ?? process.env.NEXT_PUBLIC_SUPABASE_URL;
+    const serviceRoleKey = process.env.SUPABASE_SERVICE_ROLE_KEY;
+    if (!url || !serviceRoleKey) {
+        throw new Error('vault: missing SUPABASE_URL and/or SUPABASE_SERVICE_ROLE_KEY');
+    }
+    return createClient(url, serviceRoleKey, { auth: { persistSession: false } });
+}
+export async function storeProviderKey(orgId, key, provider = DEFAULT_PROVIDER) {
+    const { error } = await adminClient().rpc('store_org_key', {
+        p_org_id: orgId,
+        p_provider: provider,
+        p_key: key,
+    });
+    if (error)
+        throw new Error(`vault: store failed (${error.code ?? 'unknown'})`);
+}
+export async function getProviderKey(orgId, provider = DEFAULT_PROVIDER) {
+    const { data, error } = await adminClient().rpc('get_org_key', {
+        p_org_id: orgId,
+        p_provider: provider,
+    });
+    if (error)
+        throw new Error(`vault: read failed (${error.code ?? 'unknown'})`);
+    return data ?? null;
+}

package/dist/redact.d.ts

@@ -0,0 +1 @@
+export declare function redactSecrets(input: unknown): string;

package/dist/redact.js

@@ -0,0 +1,26 @@
+// No-log redaction layer. Scrub secret-looking tokens from any value before it
+// is logged. Defense-in-depth: the vault module already avoids logging keys;
+// this protects every other logging path (errors, request dumps, etc.).
+const PATTERNS = [
+    /eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, // JWTs
+    /\b(?:vk|sk|sb|pk|rk|key)[_-][A-Za-z0-9_-]{8,}/gi, // provider key prefixes
+    /\b[A-Fa-f0-9]{32,}\b/g, // long hex blobs
+    /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi, // UUIDs
+];
+export function redactSecrets(input) {
+    let s;
+    if (typeof input === 'string') {
+        s = input;
+    }
+    else {
+        try {
+            s = JSON.stringify(input);
+        }
+        catch {
+            s = String(input);
+        }
+    }
+    for (const re of PATTERNS)
+        s = s.replace(re, '«redacted»');
+    return s;
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@skyhighmedia/byok-vault",
+  "version": "0.1.0",
+  "description": "BYOK provider-key vault — encrypted at rest in Supabase Vault, decrypted only server-side at point of use. The actual module SkyHighMedia apps run.",
+  "license": "MIT",
+  "type": "module",
+  "packageManager": "pnpm@11.1.1",
+  "main": "./dist/keys.js",
+  "types": "./dist/keys.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/keys.d.ts",
+      "import": "./dist/keys.js"
+    },
+    "./redact": {
+      "types": "./dist/redact.d.ts",
+      "import": "./dist/redact.js"
+    }
+  },
+  "files": [
+    "dist",
+    "sql",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Genesisapps11/byok-vault.git"
+  },
+  "keywords": [
+    "byok",
+    "supabase",
+    "vault",
+    "secrets",
+    "encryption",
+    "api-keys"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@supabase/supabase-js": ">=2"
+  },
+  "devDependencies": {
+    "@supabase/supabase-js": "^2.108.0",
+    "@types/node": "^22.10.0",
+    "@types/pg": "^8.15.0",
+    "dotenv": "^17.0.0",
+    "pg": "^8.21.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.8"
+  }
+}

package/sql/context.sql

@@ -0,0 +1,34 @@
+-- TEST FIXTURE ONLY — host apps NEVER apply this file. It is the minimal tenancy
+-- context that the DEFAULT sql/vault.sql builds on (the `orgs` table + the
+-- `current_user_org_ids()` predicate), so vault.sql applies and test/keys.test.ts
+-- runs standalone against a fresh Supabase project. Each real app brings its own
+-- tenancy (see the HOST SCHEMA CONTRACT header in sql/vault.sql).
+
+create type org_type as enum ('direct', 'agency', 'client');
+create type org_role as enum ('owner', 'admin', 'member', 'viewer', 'guardian');
+
+create table orgs (
+  id uuid primary key default gen_random_uuid(),
+  type org_type not null,
+  name text not null,
+  parent_org_id uuid references orgs(id) on delete restrict,
+  created_at timestamptz not null default now()
+);
+
+create table org_memberships (
+  id uuid primary key default gen_random_uuid(),
+  org_id uuid not null references orgs(id) on delete cascade,
+  user_id uuid not null,
+  role org_role not null default 'member',
+  unique (org_id, user_id)
+);
+
+-- Orgs the current user may access (own orgs + child orgs they own/admin).
+create or replace function current_user_org_ids()
+returns setof uuid language sql stable security definer set search_path = public as $$
+  select m.org_id from org_memberships m where m.user_id = auth.uid()
+  union
+  select o.id from orgs o
+    join org_memberships m on m.org_id = o.parent_org_id
+   where m.user_id = auth.uid() and m.role in ('owner', 'admin')
+$$;

package/sql/vault.sql

@@ -0,0 +1,93 @@
+-- BYOK key vault. Provider keys are stored in Supabase Vault — ciphertext in
+-- vault.secrets, the encryption key held by Supabase outside the DB, so a DB
+-- dump alone is useless. Plaintext is reachable ONLY via the two security-
+-- definer functions below, which are granted to service_role alone.
+--
+-- ┌─ HOST SCHEMA CONTRACT ──────────────────────────────────────────────────┐
+-- │ This template is shown with the default (SpeakOS) tenancy. Each host app │
+-- │ applies its own migration substituting TWO contract points:             │
+-- │                                                                          │
+-- │  1. TENANT TABLE the key rows reference.                                 │
+-- │       default:  org_id uuid references orgs(id)                          │
+-- │       e.g.:     tenant_id uuid references tenants(id)                    │
+-- │                                                                          │
+-- │  2. METADATA-READ PREDICATE for the SELECT RLS policy — the tenant rows  │
+-- │     the current user may see (provider + last4 only; never the key).     │
+-- │       default:  org_id in (select current_user_org_ids())               │
+-- │       e.g.:     tenant_id = (select (auth.jwt() -> 'app_metadata'        │
+-- │                              ->> 'tenant_id')::uuid)                     │
+-- │                                                                          │
+-- │ FIXED RPC CONTRACT (do NOT rename): the shared TS chokepoint             │
+-- │ (src/keys.ts) calls these functions BY NAME with these param names:      │
+-- │   store_org_key(p_org_id uuid, p_provider text, p_key text)              │
+-- │   get_org_key(p_org_id uuid, p_provider text)                            │
+-- │ Even if your tenant column is named differently, keep the function and   │
+-- │ param names and pass your tenant id as p_org_id — that is what keeps the │
+-- │ published package's keys.ts usable unchanged across apps.                │
+-- └──────────────────────────────────────────────────────────────────────────┘
+
+create table org_keys (
+  id uuid primary key default gen_random_uuid(),
+  org_id uuid not null references orgs(id) on delete cascade,   -- contract point 1
+  provider text not null default 'vapi',
+  vault_secret_id uuid not null,     -- points at vault.secrets; NOT the plaintext
+  key_last4 text not null,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now(),
+  unique (org_id, provider)
+);
+
+alter table org_keys enable row level security;
+-- Supabase's default public-table ACL grants anon/authenticated full DML. Revoke it
+-- EXPLICITLY so tenant roles cannot write key metadata (e.g. repoint vault_secret_id
+-- at another tenant's secret, or spoof key_last4). RLS already blocks writes (no
+-- permissive write policy exists), but this makes the lockdown explicit rather than
+-- "one accidental policy away".
+revoke all on org_keys from anon, authenticated;
+grant select on org_keys to authenticated;  -- metadata only (provider + last4); no plaintext lives here
+create policy org_keys_select on org_keys for select
+  using (org_id in (select current_user_org_ids()));           -- contract point 2
+-- writes go ONLY through store_org_key (security definer, service_role): no write policy + revoked DML
+
+-- Store or replace a provider key: upserts the Vault secret + the metadata row.
+create or replace function store_org_key(p_org_id uuid, p_provider text, p_key text)
+returns void language plpgsql security definer set search_path = public, vault as $$
+declare v_existing uuid; v_id uuid;
+begin
+  if p_key is null or p_key = '' then
+    raise exception 'vault: empty key';
+  end if;
+  -- Serialize concurrent writes for the same (org, provider) so two racing first-time
+  -- creates can't each call vault.create_secret and leave one secret orphaned. The
+  -- lock is transaction-scoped (released on commit/rollback).
+  perform pg_advisory_xact_lock(hashtextextended(p_org_id::text || ':' || p_provider, 0));
+  select vault_secret_id into v_existing from org_keys where org_id = p_org_id and provider = p_provider;
+  if v_existing is not null then
+    perform vault.update_secret(v_existing, p_key);
+    v_id := v_existing;
+  else
+    v_id := vault.create_secret(p_key, 'provider_key:' || p_org_id || ':' || p_provider, 'BYOK provider key');
+  end if;
+  insert into org_keys (org_id, provider, vault_secret_id, key_last4)
+    values (p_org_id, p_provider, v_id, right(p_key, 4))
+    on conflict (org_id, provider)
+    do update set vault_secret_id = excluded.vault_secret_id, key_last4 = excluded.key_last4, updated_at = now();
+end $$;
+
+-- Fetch the decrypted provider key (service_role only).
+create or replace function get_org_key(p_org_id uuid, p_provider text)
+returns text language plpgsql security definer set search_path = public, vault as $$
+declare v_id uuid; v_secret text;
+begin
+  select vault_secret_id into v_id from org_keys where org_id = p_org_id and provider = p_provider;
+  if v_id is null then return null; end if;
+  select decrypted_secret into v_secret from vault.decrypted_secrets where id = v_id;
+  return v_secret;
+end $$;
+
+revoke all on function store_org_key(uuid, text, text) from public, anon, authenticated;
+revoke all on function get_org_key(uuid, text) from public, anon, authenticated;
+grant execute on function store_org_key(uuid, text, text) to service_role;
+grant execute on function get_org_key(uuid, text) to service_role;
+
+notify pgrst, 'reload schema';