@@ -0,0 +1,21 @@
+---
+'@objectstack/core': patch
+---
+
+fix(core)!: an API key authenticates only as an owner who exists
+
+Clause-②: yes (narrowing) — a request authenticated by an API key whose owner has no user record is answered as a key that does not exist (the generic `401 UNAUTHENTICATED`), at every door that accepts a key, and never falls through to a session sent beside it. The widening half: the exported `ApiKeyRefusalReason` union gains `'owner_absent'`.
+Metadata-protocol: none
+Skills-docs: updated here — `content/docs/permissions/authentication.mdx` states the rule; the dogfood pin `api-key-owner-exists.dogfood.test.ts` exercises it.
+
+<!-- adr-0087: not-required (no-migration-prescription) No key of any schema is added, removed, renamed or re-shaped and nothing at rest changes: the owner row the key admission already reads decides it, and no key row is revoked or rewritten. -->
+
+**BREAKING** accept-set narrowing at every key-admitting door (`@objectstack/core`): an API key authenticates only as an owner who exists.
+
+- **The rule.** An API key is a credential of the user who minted it. A key whose owner has no user record is a credential of no one: it is refused where a key becomes its owner (the shared key-admission seam), with the answer a key that does not exist gets, on the REST data door (read and write), the MCP door and every other door that resolves a key. It never falls through to a session sent beside it.
+- **A store with no `sys_user` table refuses every API key.** No owner exists in such a store, so no key authenticates there. This is deliberate, and it is the same answer as a store whose `sys_user` table holds no row for the key's owner.
+- **What the operator sees.** Each refused request logs one server-side line, `[security] API key refused (owner_absent)`, naming the key's row id and the owner id, so the key to revoke is named. The caller is told nothing beyond the generic `401`.
+- **Unchanged.** A key's own lifecycle still answers first: a revoked, expired or inactive key keeps its located `403`. An owner read that fails still answers `503`. A key whose owner exists is unaffected, and no read is added: the decision uses the owner read the ban check already makes.
+- **Who moves.** An integration running on a key whose owner has no user record gets `401`.
+
+**The remedy.** Mint a replacement key while signed in as an existing user, and revoke the orphan keys in **Setup → API Keys**.
@@ -649,6 +649,13 @@ often before the account-level lock engages.
 > administrator's included. This is why a non-compliant user can sign in but
 > can't read or change data, or administer the platform, until they fix the
 > issue.
+>
+> **An API key authenticates only as an owner who exists.** A key whose owner
+> has no user record is answered on every face that admits keys exactly as a
+> key that does not exist (the generic `401 UNAUTHENTICATED`), a session sent
+> beside it never answers for it, and the server logs the refused key's row id
+> and owner id. The remedy is a new key minted by an existing user; revoke the
+> old key in **Setup → API Keys**.
 
 #### Saving, clearing and lockout recovery
 
 
@@ -13,8 +13,14 @@
  *  - not a revocation: nothing is written while the ban holds, and the same
  *    key is admitted again once it is lifted;
  *  - the key's own lifecycle still answers first;
- *  - an owner read that throws is the branded store outage; a store with no
- *    `sys_user` table holds no ban.
+ *  - an owner read that throws is the branded store outage.
+ *
+ * And, on the same owner read: an API key authenticates only as an owner who
+ * exists (maintainer ruling 2026-11-05, option B). A key whose owner the read
+ * does not find — a store with no `sys_user` table included — is `refused`
+ * (`owner_absent`) exactly as a banned owner's key is: no principal, no
+ * fall-through to the session path, the anonymous entry an unknown key gets,
+ * nothing written, and one operator line naming the key row and the owner.
  */
 
 import { describe, it, expect, vi } from 'vitest';
@@ -141,9 +147,12 @@ describe('resolveApiKeyAdmission — a banned owner\'s key is refused while the
     expect((await admit(ql)).outcome).toBe('lifecycle');
   });
 
-  it('a key whose owner row is absent keeps today\'s answer — no row holds no ban', async () => {
+  it('a key whose owner does not exist is refused (owner_absent), with no principal', async () => {
     const { ql } = makeQl(null);
-    expect((await admit(ql)).outcome).toBe('admitted');
+    const admission = await admit(ql);
+    expect(admission).toMatchObject({ outcome: 'refused', reason: 'owner_absent', keyId: 'key_1', userId: OWNER });
+    expect(admission).not.toHaveProperty('principal');
+    expect(await resolveApiKeyPrincipal(ql, headers(), NOW, undefined, undefined, undefined)).toBeUndefined();
   });
 
   it('an owner read that throws is the branded store outage, never an admission', async () => {
@@ -159,13 +168,56 @@ describe('resolveApiKeyAdmission — a banned owner\'s key is refused while the
     expect(err.code).toBe('SERVICE_UNAVAILABLE');
   });
 
-  it('a store with no sys_user table holds no ban', async () => {
-    const { ql } = makeQl({ id: OWNER, banned: true });
+  it('a store with no sys_user table has no owner who exists: the key is refused as owner_absent', async () => {
+    const { ql } = makeQl({ id: OWNER, banned: false });
     const find = ql.find.bind(ql);
     ql.find = async (object: string, opts: any) => {
       if (object === 'sys_user') throw new Error('no such table: sys_user');
       return find(object, opts);
     };
+    expect(await admit(ql)).toMatchObject({ outcome: 'refused', reason: 'owner_absent', keyId: 'key_1', userId: OWNER });
+  });
+});
+
+describe('resolveApiKeyAdmission — an API key authenticates only as an owner who exists', () => {
+  it('reads the owner by id, as the system, once — the same read the ban takes', async () => {
+    const { ql, reads } = makeQl(null);
+    await admit(ql);
+    const ownerReads = reads.filter((r) => r.object === 'sys_user');
+    expect(ownerReads).toHaveLength(1);
+    expect(ownerReads[0].opts).toMatchObject({ where: { id: OWNER }, limit: 1, context: { isSystem: true } });
+  });
+
+  it('a refusal writes nothing: the key row is not revoked and its use is not stamped', async () => {
+    const { ql, tables, update } = makeQl(null);
+    const keyRowBefore = { ...tables.sys_api_key[0] };
+    expect((await admit(ql)).outcome).toBe('refused');
+    expect(update).not.toHaveBeenCalled();
+    expect(tables.sys_api_key[0]).toEqual(keyRowBefore);
+  });
+
+  it('the key\'s own lifecycle answers first: a revoked key whose owner does not exist is refused as revoked', async () => {
+    const { ql } = makeQl(null, { revoked: true });
+    expect((await admit(ql)).outcome).toBe('lifecycle');
+  });
+
+  it('an owner read that throws is still the branded store outage, never a refusal or an admission', async () => {
+    const { ql } = makeQl(null);
+    const find = ql.find.bind(ql);
+    ql.find = async (object: string, opts: any) => {
+      if (object === 'sys_user') throw new Error('connection reset');
+      return find(object, opts);
+    };
+    const err = await admit(ql).catch((e) => e);
+    expect(isAuthzStoreUnavailableError(err)).toBe(true);
+    expect(err.status).toBe(503);
+    expect(err.code).toBe('SERVICE_UNAVAILABLE');
+  });
+
+  it('control: the same key is admitted once its owner exists', async () => {
+    const { ql, tables } = makeQl(null);
+    expect((await admit(ql)).outcome).toBe('refused');
+    tables.sys_user.push({ id: OWNER });
     expect((await admit(ql)).outcome).toBe('admitted');
   });
 });
@@ -210,6 +262,42 @@ describe('resolveAuthzContext — a banned owner\'s key resolves as a key that d
     }
   });
 
+  it('a key whose owner does not exist resolves the same context a made-up key resolves, and the operator line names the key and the owner', async () => {
+    const { ql } = makeQl(null);
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const refusalLines = () => warn.mock.calls.flat().map(String).filter((l) => l.includes('API key refused'));
+      const absent = await resolve(ql, KEY);
+      expect(refusalLines()).toHaveLength(1);
+      const madeUp = await resolve(ql, MADE_UP_KEY);
+      expect(absent.userId).toBeUndefined();
+      expect(absent.credential).toBeUndefined();
+      expect(absent).toEqual(madeUp);
+      // One line, server-side only, naming the reason, the key row id and the owner id.
+      const [line] = refusalLines();
+      expect(line).toContain('(owner_absent)');
+      expect(line).toContain('key=key_1');
+      expect(line).toContain(`principal=${OWNER}`);
+      // The made-up key is not a refusal: it adds no line.
+      expect(refusalLines()).toHaveLength(1);
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it('a key whose owner does not exist never falls through to a session sent beside it', async () => {
+    const { ql } = makeQl(null);
+    const getSession = vi.fn(async () => ({ user: { id: COOKIE_USER }, session: { userId: COOKIE_USER } }));
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const authz = await resolve(ql, KEY, getSession);
+      expect(authz.userId).toBeUndefined();
+      expect(getSession).not.toHaveBeenCalled();
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
   it('control: a non-banned owner\'s key resolves the owner, credential api_key', async () => {
     const { ql } = makeQl({ id: OWNER, banned: false });
     const authz = await resolve(ql, KEY);
@@ -238,10 +326,10 @@ describe('a refused key gets the anonymous entry an unknown key gets, on a face
   const ORG = 'org_only';
 
   /** A guest anchor that grants something, in the one organization the guest entry derives. */
-  function guestServingQl(keyRow: Record<string, unknown>, owner: Record<string, unknown>) {
+  function guestServingQl(keyRow: Record<string, unknown>, owner: Record<string, unknown> | null) {
     const tables: Record<string, any[]> = {
       sys_api_key: [{ id: 'key_1', key: hashApiKey(KEY), user_id: OWNER, revoked: false, scopes: '[]', ...keyRow }],
-      sys_user: [owner],
+      sys_user: owner ? [owner] : [],
       sys_member: [],
       sys_organization: [{ id: ORG }],
       sys_metadata_activation: [],
@@ -293,4 +381,15 @@ describe('a refused key gets the anonymous entry an unknown key gets, on a face
     expect(banned.userId).toBeUndefined();
     expect(banned).toEqual(unknown);
   });
+
+  it('a key whose owner does not exist and an unknown key get the same guest entry', async () => {
+    const ql = guestServingQl({}, null);
+    const absent = await quietly(() => onGuestFace(ql, KEY));
+    const unknown = await onGuestFace(ql, MADE_UP_KEY);
+    // Non-vacuous: the guest anchor really grants something here.
+    expect(unknown.permissions).toEqual([GUEST_SET]);
+    expect(unknown.tenantId).toBe(ORG);
+    expect(absent.userId).toBeUndefined();
+    expect(absent).toEqual(unknown);
+  });
 });
@@ -57,12 +57,15 @@ interface Recorded { object: string; data: Record<string, unknown> }
 function makeQl(row: Record<string, unknown>, opts: { failUpdate?: boolean } = {}) {
   const updates: Recorded[] = [];
   const rows: any[] = [{ id: KEY_ID, key: hashApiKey(RAW), prefix: 'osk_lifecycl', user_id: OWNER, revoked: false, ...row }];
+  // The key's owner exists: an API key authenticates only as an owner who exists.
+  const tables: Record<string, any[]> = { sys_api_key: rows, sys_user: [{ id: OWNER }] };
   const ql = {
     updates,
     find: async (object: string, findOpts: any) => {
-      if (object !== 'sys_api_key') return [];
+      const table = tables[object];
+      if (!table) return [];
       const where = findOpts?.where ?? {};
-      const matched = rows.filter((r) => Object.entries(where).every(([k, v]) => {
+      const matched = table.filter((r) => Object.entries(where).every(([k, v]) => {
         if (k.startsWith('$')) throw new Error(`fake driver: unsupported operator ${k}`);
         return r[k] === v;
       }));
 
@@ -63,11 +63,16 @@ function matchesWhere(row: any, where: any): boolean {
   return true;
 }
 
-/** `sys_api_key` holds `rows`, matched by `where` and bounded by `limit`. */
+/**
+ * `sys_api_key` holds `rows`, matched by `where` and bounded by `limit`;
+ * `sys_user` holds the owners `rows` name (an API key authenticates only as an
+ * owner who exists), matched the same way.
+ */
 function qlWithKeyRows(rows: any[]) {
+  const owners = [...new Set(rows.map((r) => r.user_id).filter((id) => typeof id === 'string' && id))].map((id) => ({ id }));
   return {
     find: async (object: string, q: any = {}) => {
-      const table = object === 'sys_api_key' ? rows : [];
+      const table = object === 'sys_api_key' ? rows : object === 'sys_user' ? owners : [];
       const found = table.filter((r) => matchesWhere(r, q?.where));
       return typeof q?.limit === 'number' ? found.slice(0, q.limit) : found;
     },
 
@@ -13,19 +13,30 @@ import {
   effectiveTenancyPosture,
 } from './api-key.js';
 
+/**
+ * The owners the key rows name, as `sys_user` rows: an API key authenticates
+ * only as an owner who exists, so a fixture whose keys should authenticate
+ * says their owners exist. Pass `users` to `makeQl` to say otherwise.
+ */
+function ownersOf(rows: any[]): any[] {
+  return [...new Set(rows.map((r) => r.user_id).filter((id) => typeof id === 'string' && id))].map((id) => ({ id }));
+}
+
 /**
  * In-memory sys_api_key store exposing the `find` shape the verifier uses.
  *
  * [commit 4c9780c7a] `limit` is ENFORCED — presence, not truthiness, so `limit: 0` returns
  * nothing rather than everything. A double that drops the bound makes any limit
  * change on this read green by construction; the verifier reads with `limit: 1`.
  */
-function makeQl(rows: any[]) {
+function makeQl(rows: any[], users: any[] = ownersOf(rows)) {
+  const tables: Record<string, any[]> = { sys_api_key: rows, sys_user: users };
   return {
     find: async (object: string, opts: any) => {
-      if (object !== 'sys_api_key') return [];
+      const table = tables[object];
+      if (!table) return [];
       const where = opts?.where ?? {};
-      const matched = rows.filter((r) => Object.entries(where).every(([k, v]) => { if (k.startsWith('$')) throw new Error(`fake driver: unsupported operator ${k}`); return r[k] === v; }));
+      const matched = table.filter((r) => Object.entries(where).every(([k, v]) => { if (k.startsWith('$')) throw new Error(`fake driver: unsupported operator ${k}`); return r[k] === v; }));
       return typeof opts?.limit === 'number' ? matched.slice(0, opts.limit) : matched;
     },
   };