feat(runtime): bind an artifact's install-time granted permissions to its plugins at load (#17137)

* feat(runtime): bind the artifact's install-time granted permissions per plugin at load

Wire `EnvironmentArtifactSchema.grantedPermissions` into
`PluginPermissionEnforcer.registerGrantedPermissions` at materialize time —
the consumer half the artifact contract names, and the key-to-plugin binding
that did not exist before: one `AppPlugin` covers a whole artifact, so nothing
in the load path could say which package a grant entry belonged to.

Absent, `{}` and a consented entry stay three distinct states, both directions.

Claude-Session: https://claude.ai/code/session_01XTBcV7zZHmokdyQgXjbyEU
Co-authored-by: Claude <noreply@anthropic.com>

* chore(changeset): declare the artifact granted-permissions load binding

Claude-Session: https://claude.ai/code/session_01XTBcV7zZHmokdyQgXjbyEU
Co-authored-by: Claude <noreply@anthropic.com>

* fix(runtime): carry `grantedPermissions` across the artifact envelope unwrap

The `{ schemaVersion, metadata }` unwrap hands the kernel `metadata` alone and
drops every key beside it, so the install-time consented set — which the
artifact contract puts BESIDE `metadata` — never reached the loader that the
contract names as its consumer. Silent, and indistinguishable from the
legitimate "no consent record" reading.

Claude-Session: https://claude.ai/code/session_01XTBcV7zZHmokdyQgXjbyEU
Co-authored-by: Claude <noreply@anthropic.com>

* fix(runtime): name the grant binding for what it does, and drop the forbidden `?? {}`

Contract-review rework on #13457. Behaviour is unchanged in every leg; what
moves is naming, one redundant default, and two test assertions that could not
tell the doors apart.

- `ArtifactGrantBinding.gated` / `ungated` -> `registered` / `unregistered`,
  and the `[AppPlugin]` log line with them. The old names claimed a gate that
  does not exist: this round REGISTERS a consent set and nothing on this tree
  queries the registry, which the type's own docblock already said
  ("registered on the enforcer"). The loader comment "the gate had nothing to
  enforce" presupposed the same absent gate.

- Delete `.grantedPermissions ?? {}` in `registerArtifactGrantedPermissions`.
  It was a semantic no-op, but it is the exact spelling `app-plugin.ts` forbids
  by name on this key. Replaced by the narrowing that states the fact the walk
  already established: `registered` is non-empty only on the plain-record
  branch, so the loop reads the carrier's own record or iterates nothing.

- Correct the "closed by two doors" claim. `{ id: '', name: 'x' }` passes BOTH
  doors, because `artifactPackageId` is `id || name`; the fixture set id and
  name to `''` together and hid the fallback. The escaping case is now pinned,
  including its fail-OPEN reading through the enforcer's own readback: the
  unattributable `''` key binds to nothing, is reported `unbound`, and denies
  nothing. No refusal is added -- that fork is #17148.

- Tighten both door tests. Each asserted `/no usable package id|not a package
  entry/`, so either passed on either door and neither pinned which fired.
  Both doors raise the same ADR-0112 code and status, so each test now pins the
  shared envelope plus the message unique to its own door, and asserts the
  other door's message is absent.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XTBcV7zZHmokdyQgXjbyEU

---------

Co-authored-by: os-sam <sam@objectstack.ai>
Co-authored-by: Claude <noreply@anthropic.com>

Author: 3 people

.changeset/artifact-granted-permissions-load-binding.md

@@ -0,0 +1,15 @@
+---
+'@objectstack/runtime': minor
+---
+
+Bind an environment artifact's install-time GRANTED permission set to the packages that artifact materializes.
+
+`EnvironmentArtifactSchema.grantedPermissions` — the consented `{ services, hooks, network, fs }` set the control plane compiles onto the artifact at install-consent time (ADR-0025 §3.5 step 2 / F4) — now reaches `PluginPermissionEnforcer.registerGrantedPermissions` at materialize time, one call per consent record, keyed by the plugin manifest `id`. `AppPlugin.init()` performs the binding, so it happens on every path that turns an artifact into a kernel plugin without either caller changing a line, and the enforcer holding the result is readable as `AppPlugin.permissionEnforcer` (with `AppPlugin.grantBinding` recording what bound).
+
+Absent, `{}` and a consented entry stay three distinct states. An artifact carrying no `grantedPermissions` key allocates no enforcer and registers nothing, so a package with no consent record loads exactly as it did; a per-plugin `{}` is a consent record that consented to nothing and registers a bag that denies every service, hook, host and path. A consent record naming a package the artifact does not carry is reported at `warn` rather than passing in silence.
+
+Fixed alongside, because without it the binding was unreachable: the `{ schemaVersion, metadata }` envelope unwrap in `loadArtifactBundle` handed the kernel `metadata` alone and dropped every key standing beside it, so an envelope artifact reached the kernel with `grantedPermissions` stripped. The loss was silent and indistinguishable from the legitimate absent reading. The unwrap now carries the key across when the envelope declares it, `{}` included, and never invents one.
+
+New exports from `@objectstack/runtime`: `registerArtifactGrantedPermissions`, `resolveArtifactGrantBinding`, `carriedPackageIds`, `ArtifactGrantBinding`.
+
+This is the registration half. Access-time enforcement runs through `SecurePluginContext`, which no production path constructs; that seam is ADR-0025 install-flow work and is unchanged here.

packages/runtime/src/app-plugin.granted-permissions.test.ts

@@ -0,0 +1,98 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// #13457 — `AppPlugin.init()` is the ONE production caller of the artifact→
+// enforcer seam, and this file pins that it is: the wiring, not the seam's own
+// logic (that is `security/artifact-granted-permissions.test.ts`).
+//
+// The site matters as much as the behaviour. `AppPlugin` is the single point
+// where an environment artifact becomes a kernel plugin on BOTH paths — the
+// self-hosted `createStandaloneStack` and the cloud control plane's
+// `ArtifactKernelFactory`, which constructs the same object — so a consent
+// record reaches the enforcer without either caller changing a line. Before
+// this, `PluginPermissionEnforcer` had zero production callers (#7500,
+// re-measured on this branch).
+
+import { describe, it, expect, vi } from 'vitest';
+import { AppPlugin } from './app-plugin.js';
+import type { PluginContext } from '@objectstack/core';
+
+const bootCtx = () => {
+    const logger = { info: vi.fn(), error: vi.fn(), warn: vi.fn(), debug: vi.fn() };
+    return {
+        logger,
+        registerService: vi.fn(),
+        registerServiceFactory: vi.fn(),
+        replaceService: vi.fn(),
+        getService: vi.fn((name: string) => (name === 'manifest' ? { register: vi.fn() } : undefined)),
+        getServices: vi.fn(() => new Map()),
+        getServiceScoped: vi.fn(),
+        hook: vi.fn(),
+        trigger: vi.fn(),
+        getKernel: vi.fn(),
+    } as unknown as PluginContext & { logger: typeof logger };
+};
+
+const bundle = (extra: Record<string, unknown> = {}) => ({
+    manifest: { id: 'com.acme.crm', name: 'Acme CRM', version: '1.0.0', type: 'app' },
+    packages: [
+        { manifest: { id: 'com.acme.crm', name: 'crm', version: '1.0.0', type: 'app' } },
+        { manifest: { id: 'com.acme.reports', name: 'reports', version: '1.0.0', type: 'module' } },
+    ],
+    ...extra,
+});
+
+describe('#13457 — AppPlugin.init binds the artifact\'s granted permissions', () => {
+    it('an artifact with NO grantedPermissions key allocates no enforcer at all', async () => {
+        const ctx = bootCtx();
+        const plugin = new AppPlugin(bundle());
+        await plugin.init(ctx);
+
+        // ⭐ Not "an enforcer that denies nothing" — no enforcer. This is every
+        // artifact that ships today, and the boot has to be byte-for-byte what
+        // it was: absent is no consent record, never a deny.
+        expect(plugin.permissionEnforcer).toBeUndefined();
+        expect(plugin.grantBinding).toBeUndefined();
+    });
+
+    it('a consent-bearing artifact registers each entry under its manifest id', async () => {
+        const ctx = bootCtx();
+        const plugin = new AppPlugin(bundle({
+            grantedPermissions: { 'com.acme.crm': { services: ['object'], hooks: [] } },
+        }));
+        await plugin.init(ctx);
+
+        const e = plugin.permissionEnforcer;
+        expect(e).toBeDefined();
+        // Keyed by the plugin manifest `id` — ⛔ never the kernel plugin name
+        // (`plugin.app.com.acme.crm`), which is what `AppPlugin` registers
+        // ITSELF under and is not the key the artifact contract writes.
+        expect(plugin.name).toBe('plugin.app.com.acme.crm');
+        expect(e!.getPluginPermissions('com.acme.crm')!.canAccessService('object')).toBe(true);
+        expect(e!.getPluginPermissions('com.acme.crm')!.canAccessService('storage')).toBe(false);
+        // The sibling package carries no consent record — nothing registered for it.
+        expect(e!.getPluginPermissions('com.acme.reports')).toBeUndefined();
+        expect(plugin.grantBinding).toMatchObject({
+            declared: true,
+            registered: ['com.acme.crm'],
+            unregistered: ['com.acme.reports'],
+            unbound: [],
+        });
+    });
+
+    it('binds on an EMPTY environment too, so a grant that binds to nothing is still heard', async () => {
+        // An empty env has no app payload and `init()` returns early — but the
+        // binding runs BEFORE that return, because an artifact carrying grants
+        // for packages it does not ship is exactly the fault that shows up here.
+        const ctx = bootCtx();
+        const plugin = new AppPlugin({
+            manifest: { plugins: [], drivers: [] },
+            grantedPermissions: { 'com.acme.ghost': { services: ['object'] } },
+        });
+        await plugin.init(ctx);
+
+        expect(plugin.grantBinding).toMatchObject({ declared: true, registered: [], unbound: ['com.acme.ghost'] });
+        expect(
+            ctx.logger.warn.mock.calls.some((c: unknown[]) => String(c[0]).includes('bound to NO package')),
+        ).toBe(true);
+    });
+});

packages/runtime/src/app-plugin.ts

@@ -1,7 +1,17 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
-import { Plugin, PluginContext, wireAuthoredTranslationSync } from '@objectstack/core';
+import {
+    Plugin,
+    PluginContext,
+    createPluginPermissionEnforcer,
+    wireAuthoredTranslationSync,
+    type PluginPermissionEnforcer,
+} from '@objectstack/core';
 import { resolveArtifactCollections } from './artifact-collections.js';
+import {
+    registerArtifactGrantedPermissions,
+    type ArtifactGrantBinding,
+} from './security/artifact-granted-permissions.js';
 import { applyArtifactForwardConversions, assertProtocolCompat } from '@objectstack/metadata-core';
 import { resolveTenancyPosture } from '@objectstack/types';
 import { postureEnforcesWall, type TenancyPosture } from '@objectstack/spec/security';
@@ -125,6 +135,22 @@ export class AppPlugin implements Plugin {
      * of arriving at teardown time.
      */
     private initCtx?: PluginContext;
+    /**
+     * The enforcer holding this artifact's install-time GRANTED permission sets
+     * (ADR-0025 F4), or `undefined` when the artifact carried no
+     * `grantedPermissions` key — which is every artifact built before consent
+     * existed and every `defineStack()` config, so this stays `undefined` on
+     * every boot shape that ships today.
+     *
+     * Constructed in `init()` only when there is something to register, so a
+     * boot with no consent record allocates nothing and behaves byte-for-byte
+     * as it did. Public and readonly-by-accessor so the materialize seam that
+     * will QUERY it — and a composition pin — can reach the registry rather
+     * than rebuilding it from the artifact a second time.
+     */
+    private grantEnforcer?: PluginPermissionEnforcer;
+    /** What `grantedPermissions` bound to on this artifact — see {@link ArtifactGrantBinding}. */
+    private grantBindingResult?: ArtifactGrantBinding;
     /** When true, init/start become no-ops — env has no app payload. */
     private readonly empty: boolean = false;
     /**
@@ -171,6 +197,29 @@ export class AppPlugin implements Plugin {
         return (this.resolvedCollections ??= resolveArtifactCollections(this.bundle));
     }
 
+    /**
+     * The enforcer this artifact's consent records were registered on, or
+     * `undefined` when the artifact declared no `grantedPermissions` key.
+     *
+     * ⛔ `undefined` here means "no consent record for this environment", NEVER
+     * "denied": a caller that reads `undefined` as a deny bricks every boot
+     * shape that ships today (clause 1.3). The three states this distinguishes
+     * are written out on `registerArtifactGrantedPermissions`.
+     */
+    get permissionEnforcer(): PluginPermissionEnforcer | undefined {
+        return this.grantEnforcer;
+    }
+
+    /**
+     * What the artifact's `grantedPermissions` map bound to on this boot —
+     * `undefined` when the key was absent. Public so a composition pin can read
+     * the binding without re-deriving it, and so a caller can tell a declared
+     * empty map (`declared: true`, nothing registered) from an absent one.
+     */
+    get grantBinding(): ArtifactGrantBinding | undefined {
+        return this.grantBindingResult;
+    }
+
     constructor(
         bundle: any,
         projectContext?: AppPluginProjectContext,
@@ -264,6 +313,16 @@ export class AppPlugin implements Plugin {
         // empty-env early return, so teardown is armed on every path init
         // takes.
         this.initCtx = ctx;
+        // Bind the install-time GRANTED permission set (ADR-0025 F4, #13457)
+        // BEFORE anything this plugin registers on the kernel. This is the
+        // materialize-time moment the artifact contract names as the consumer
+        // of `EnvironmentArtifactSchema.grantedPermissions`, and it runs ahead
+        // of the empty-env return on purpose: a consent record that binds to
+        // nothing has to be heard on an empty environment too, which is exactly
+        // where an artifact carrying grants for packages it does not ship shows
+        // up. A no-op — not even an allocation — on every artifact that carries
+        // no `grantedPermissions` key.
+        this.bindGrantedPermissions(ctx);
         // Install the engine-wide default hook body runner FIRST — even for
         // empty envs (an empty env is exactly where a user will author their
         // first Studio hook). Runs in init (Phase 1) so it is in place before
@@ -326,6 +385,38 @@ export class AppPlugin implements Plugin {
         ctx.getService<{ register(m: any): void }>('manifest').register(servicePayload);
     }
 
+    /**
+     * Register the install-time GRANTED permission set this artifact carries,
+     * one entry per consent-bearing package, on an enforcer this plugin owns
+     * (ADR-0025 F4 / #13457 — the consumer half of
+     * `EnvironmentArtifactSchema.grantedPermissions`).
+     *
+     * The whole method is behind the `=== undefined` gate below, and that gate
+     * is the clause-1.3 guarantee in code: an artifact with no consent record
+     * takes no branch, allocates no enforcer and registers nothing, so ABSENT
+     * can never become "denied". `{}` is not absent and does not take the early
+     * return — a declared-but-empty map is a consent record that names no
+     * package, which is a different reading and is recorded as one.
+     *
+     * ⛔ Never `??`/`||` on `grantedPermissions`: both spellings turn a declared
+     * `{}` into absence and erase a distinction the producer pins both ways.
+     */
+    private bindGrantedPermissions(ctx: PluginContext): void {
+        if ((this.bundle as { grantedPermissions?: unknown } | null | undefined)?.grantedPermissions === undefined) {
+            return;
+        }
+        const enforcer = createPluginPermissionEnforcer(ctx.logger);
+        const binding = registerArtifactGrantedPermissions(this.bundle, enforcer, { logger: ctx.logger });
+        this.grantEnforcer = enforcer;
+        this.grantBindingResult = binding;
+        ctx.logger.info('[AppPlugin] registered install-time granted permissions', {
+            pluginName: this.name,
+            registered: [...binding.registered],
+            unregistered: [...binding.unregistered],
+            unbound: [...binding.unbound],
+        });
+    }
+
     /**
      * Seed persisted package disable-state into the registry's initial-disabled
      * set, so every later registration path — boot artifact decomposition,

packages/runtime/src/index.ts

@@ -140,6 +140,10 @@ export {
     type RateLimitKeyKind,
     type RateLimitLogger,
     type ActorUser,
+    carriedPackageIds,
+    resolveArtifactGrantBinding,
+    registerArtifactGrantedPermissions,
+    type ArtifactGrantBinding,
 } from './security/index.js';
 
 // ── Observability primitives ──────────────────────────────────────────

packages/runtime/src/load-artifact-bundle.granted-permissions.test.ts

@@ -0,0 +1,70 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// #13457 — the `{ schemaVersion, metadata }` unwrap must carry
+// `grantedPermissions` across.
+//
+// `EnvironmentArtifactSchema` puts the install-time consented set BESIDE
+// `metadata`, and the unwrap hands the kernel `metadata` alone — so every key
+// standing beside it is dropped. For `grantedPermissions` that loss is SILENT
+// and indistinguishable from the legitimate reading: an absent key means "no
+// consent record", so an envelope stripped of its consent records boots green,
+// enforcing nothing, with nothing to see. That is why this is pinned on the
+// loader rather than left to the consumer.
+
+import { describe, it, expect } from 'vitest';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { loadArtifactBundle } from './load-artifact-bundle.js';
+
+const write = (body: unknown): string => {
+    const dir = mkdtempSync(join(tmpdir(), 'os-13457-'));
+    const file = join(dir, 'objectstack.json');
+    writeFileSync(file, JSON.stringify(body), 'utf-8');
+    return file;
+};
+
+const envelope = (extra: Record<string, unknown>) => ({
+    schemaVersion: '0.1',
+    environmentId: 'env_1',
+    commitId: 'c1',
+    checksum: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
+    metadata: { manifest: { id: 'com.acme.crm', name: 'crm', version: '1.0.0', type: 'app' } },
+    ...extra,
+});
+
+describe('#13457 — the envelope unwrap carries the consented set', () => {
+    it('a populated `grantedPermissions` survives the unwrap', async () => {
+        const grants = { 'com.acme.crm': { services: ['object'], hooks: [], network: [], fs: [] } };
+        const bundle = await loadArtifactBundle(write(envelope({ grantedPermissions: grants })), {
+            unwrapEnvelope: true,
+        });
+        // The unwrapped bundle is `metadata`; the consented set rode across.
+        expect(bundle.manifest.id).toBe('com.acme.crm');
+        expect(bundle.grantedPermissions).toEqual(grants);
+    });
+
+    it('a declared EMPTY map survives as `{}` — not as absence', async () => {
+        const bundle = await loadArtifactBundle(write(envelope({ grantedPermissions: {} })), {
+            unwrapEnvelope: true,
+        });
+        // ⭐ `{}` is a consent record that names no package. A truthiness or
+        // emptiness test in the carry would drop it and turn it into the absent
+        // reading, which is the collapse the producer pins against.
+        expect(bundle.grantedPermissions).toEqual({});
+        expect('grantedPermissions' in bundle).toBe(true);
+    });
+
+    it('an envelope with NO `grantedPermissions` does not grow one', async () => {
+        const bundle = await loadArtifactBundle(write(envelope({})), { unwrapEnvelope: true });
+        expect('grantedPermissions' in bundle).toBe(false);
+    });
+
+    it('an UNWRAPPED artifact is untouched — the carry is the unwrap\'s business only', async () => {
+        // No `schemaVersion`, so nothing unwraps and the parsed object is the
+        // bundle; the key (present or not) is already where the consumer reads.
+        const flat = { manifest: { id: 'com.acme.crm' }, grantedPermissions: { 'com.acme.crm': {} } };
+        const bundle = await loadArtifactBundle(write(flat), { unwrapEnvelope: true });
+        expect(bundle.grantedPermissions).toEqual({ 'com.acme.crm': {} });
+    });
+});

packages/runtime/src/load-artifact-bundle.ts

@@ -85,9 +85,29 @@ export async function loadArtifactBundle(
     try {
         const raw = await readArtifactSource(absArtifactPath, { fetchTimeoutMs: opts.fetchTimeoutMs });
         const parsed = JSON.parse(raw);
-        bundle = opts.unwrapEnvelope && parsed?.schemaVersion != null && parsed?.metadata !== undefined
-            ? parsed.metadata
-            : parsed;
+        const unwrapping = Boolean(opts.unwrapEnvelope)
+            && parsed?.schemaVersion != null && parsed?.metadata !== undefined;
+        bundle = unwrapping ? parsed.metadata : parsed;
+        // [#13457] The unwrap keeps `metadata` and DROPS every key standing
+        // beside it, so an envelope key whose declared consumer is this loader
+        // has to be carried across by name or it is silently gone.
+        // `grantedPermissions` is that key: `EnvironmentArtifactSchema` puts the
+        // install-time consented set BESIDE `metadata` (outside the checksum
+        // digest), and names the materialize-time loader as its consumer — so
+        // before this line an envelope artifact reached the kernel with every
+        // consent record stripped, and the enforcer had nothing to register.
+        // (⛔ Not "the gate had nothing to enforce": there is no gate — this
+        // round fills the registry, and nothing on this tree queries it yet.)
+        // Nothing threw: the key was simply absent, which is also a legitimate
+        // reading ("no consent record"), which is why it could be lost in
+        // silence.
+        // ⛔ `!== undefined`, never a truthiness or emptiness test: `{}` is a
+        // consent record that consented to nothing and must survive the unwrap
+        // as `{}`, while a genuinely absent key must NOT be created here.
+        if (unwrapping && parsed.grantedPermissions !== undefined
+            && bundle !== null && typeof bundle === 'object') {
+            bundle.grantedPermissions = parsed.grantedPermissions;
+        }
     } catch (err: any) {
         // An ABSENT artifact is not a failure (#4085). The platform is a
         // development platform first: `os serve objectstack.config.ts` boots