feat(core): S-6 plugin:doctor + plugin_extension_identifier guard + threat model (closes Lote S)

The last slice of Lote S. Adds operator-facing diagnostics, the fourth plugin-surface
Isthmus guard, and the published trust-boundary threat model.

- guard.plugin_extension_identifier: the branded-name minters (sdk/brands.ts) now
  validate with the non-emitting isSafeIdentifier predicate and emit their OWN
  plugin-surface guard on a reject (distinct from the tenant-DDL guard.tenant_identifier),
  so a hostile plugin identifier reads apart from a bad tenant id. Same accept/reject
  set. Registry entry + matrix recipe + fuzz-spec assertion updated.
- plugin:doctor command + pure PluginDoctorService: diagnoses the deployed platform
  posture from the discovered manifests + trust/firewall config — Satellite ABI drift
  (error/warn), native-addon sandbox risk, dead TRUSTED_SATELLITES entries, a missing
  read-only firewall while untrusted plugins are installed, and a disclosure of every
  declared (consent-gated) permission. It does NOT introspect specs (that is the
  check-plugin-permissions CI guard). Full command ceremony (commands.json, index,
  commands.md); the service is unit-tested per check.
- Threat model: docs/guides/security.md gains the five-layer plugin trust-boundary
  matrix (S1..S5 + the in-process-sandbox non-goal, each verdict real/friction) plus
  hardening-checklist items; stability.md gets a plugin-platform row (Experimental);
  .github/SECURITY.md states the sandbox-escape non-goal.
- Coverage floors ratcheted lines/statements 64 -> 65.

Verified via a 4-lens adversarial review (bypass/tests/ceremony/honesty); 3 low findings
folded in (severity assertions for 3 doctor checks, disclose ALL declared permission
kinds not a subset, corrected a stale plugin_env comment).

Gates green: core unit 1575, tsc 0 all workspaces, check 43/43, api-report 3/3, lint 0,
Isthmus audit-coverage 100% (23 registered guards), coverage green at the new floors.

Lote S (S-0..S-6) is complete. Merge order stays A -> S -> B -> C.

Author: Arcoders

.github/SECURITY.md

@@ -31,3 +31,9 @@ Reports against the core isolation guarantees (cross-tenant read or write
 leakage, resolver hijack, fail-open under dependency outage) are highest
 priority. See the [stability matrix](https://arcoders.github.io/Adonisjs-lasagna-saas-tenancy/reference/stability)
 for the per-feature labels.
+
+An installed plugin/satellite runs in-process with full privilege by design, so an
+**in-process plugin sandbox escape is not a goal** — the in-process trust controls are
+friction, and the hard boundary for an untrusted plugin's write is the read-only
+Postgres role (S3). The [plugin platform trust boundary](https://arcoders.github.io/Adonisjs-lasagna-saas-tenancy/guides/security#plugin-platform-trust-boundary)
+in the security guide states the five-layer model and what each layer does and does not contain.

docs/guides/security.md

@@ -69,6 +69,30 @@ PostgreSQL and Redis (no mocks) under contention.
 | Cache namespace collision | [`tests/@guarantees/behavior/integration/behavior_cache_for.spec.ts`](https://github.com/Arcoders/Adonisjs-lasagna-saas-tenancy/blob/master/packages/core/tests/@guarantees/behavior/integration/behavior_cache_for.spec.ts) — per-tenant BentoCache namespaces never share keys. |
 | Cross-tenant IDOR via tenant-id swap | [`tests/@guarantees/security/integration/security_tenant_guard_authorize.spec.ts`](https://github.com/Arcoders/Adonisjs-lasagna-saas-tenancy/blob/master/packages/core/tests/@guarantees/security/integration/security_tenant_guard_authorize.spec.ts): with `authorizeTenantAccess` wired, a caller whose principal belongs to tenant A gets 403 when resolving to tenant B. |
 
+## Plugin platform trust boundary
+
+A satellite installed as a provider runs **in-process with full privilege**. The
+plugin platform does not pretend otherwise: an installed plugin can `import` any
+module and reach any singleton, so nothing implemented in JavaScript is a sandbox.
+The controls below raise the cost of a careless or opportunistic plugin and give an
+operator an honest, consented install, but only two of them are hard boundaries, and
+both are enforced outside the JavaScript VM.
+
+| Layer | Control | Enforced by | Verdict |
+|---|---|---|---|
+| **S1 — Install consent** | The plugin declares its sensitive `permissions`; `configure` shows them and refuses a non-interactive install without `--accept-permissions`. | A human at install time | Real gate (human) |
+| **S2 — Supply chain** | Native-addon install gate (`--allow-native`), plus `lasagna:health-check` (`npm audit` over the tree, install-script and native-addon flags). | Install / CI | Real (raises the bar; not runtime) |
+| **S3 — Read-only DB role** | Untrusted plugin code is routed to a per-tenant connection authenticated as a `NOSUPERUSER NOBYPASSRLS` role with `default_transaction_read_only = on`. | PostgreSQL | **Hard boundary** (Postgres denies the write) |
+| **S4 — Out-of-process worker** | Background plugin code (scheduler / data-change, once Lote B/C land) runs in a dedicated worker under the Node Permission Model (`--permission`, fs/child_process narrowed). A native-addon plugin fails boot without `--allow-addons`. | Node runtime + orchestrator | Real when configured (native addons opt out — treat as trusted) |
+| **S5 — In-process friction** | Trusted-list proxies over the tenant repository and the db handle; an allowlist over sensitive capability provide/consume. | JavaScript | **Friction, not a boundary** (a direct import reaches around it) |
+| In-process sandbox escape | — | — | **Non-goal** — an installed plugin has full in-process reach by design |
+
+The one control that actually denies an untrusted plugin's write is **S3, the
+read-only Postgres role**. Configure it (`plugins.readOnly`) and put untrusted
+third-party plugins outside `TRUSTED_SATELLITES`. `plugin:doctor` reports the standing
+posture: ABI drift, native-addon risk, a stale trust allowlist, and a missing read-only
+firewall. See the [plugins guide](/guides/plugins) for authoring against these controls.
+
 ## Hardening checklist for production
 
 Before going live, work through this list; every item is a host
@@ -87,6 +111,7 @@ responsibility (the package gives you the primitives).
 - [ ] OIDC `client_secret`, encryption keys, and S3 credentials live in a secrets manager, not `.env` checked into git.
 - [ ] `tenant:secrets:reencrypt` has been run **before upgrading** (it brings every stored webhook/SSO secret to the current `APP_KEY` and its per-class context). Reads now fail closed, so any secret left under the legacy shared context or in plaintext stops working until migrated. Run with `OLD_APP_KEY` set for a key rotation, or unset for a context-only migration; it is idempotent and resumable.
 - [ ] `tenant:doctor` runs on a cron in production (the [doctor command](/reference/commands#tenant-doctor)) and pages on `error`-level findings.
+- [ ] If you install third-party satellites: `plugins.readOnly` is configured (the S3 Postgres read-only role), untrusted plugins are kept off `TRUSTED_SATELLITES`, and `plugin:doctor` runs alongside `tenant:doctor` (see the [plugin platform trust boundary](#plugin-platform-trust-boundary)). Native-addon plugins are treated as fully trusted — they cannot be sandboxed by the worker Permission Model.
 - [ ] Health probes wired (`/livez`, `/readyz`, `/healthz`, `/metrics`); see [Health & metrics](/guides/health).
 
 ## Reporting vulnerabilities

docs/reference/commands.md

@@ -61,6 +61,18 @@ advisory, so it doubles as a CI gate.
 node ace lasagna:health-check
 ```
 
+`plugin:doctor` diagnoses the installed plugin/satellite platform posture: Satellite
+ABI compatibility of each installed satellite, native-addon sandbox risk, a stale or
+typo'd `TRUSTED_SATELLITES` allowlist, whether the read-only firewall (`plugins.readOnly`)
+is configured while untrusted plugins are installed, and which plugins hold declared
+(consent-gated) permissions. It exits non-zero on any error, so it doubles as a CI gate. It does not
+re-check manifest↔spec coherence — that is the `check-plugin-permissions` build guard.
+
+```bash
+node ace plugin:doctor
+node ace plugin:doctor --json
+```
+
 ## Doctor
 
 `tenant:doctor` is the operational health command. Nine built-in

docs/reference/stability.md

@@ -98,6 +98,7 @@ The isolation substrate. Everything here is **release candidate** unless noted.
 | Health probes (`/livez`, `/readyz`, `/healthz`) | Release candidate | |
 | Doctor (base checks) | Release candidate | |
 | Plans and quotas (`enforceQuota`) | Experimental | Opt-in feature, not part of the isolation guarantee. |
+| Plugin platform (`definePlugin`, request-path seams, capability registry, trust controls) | Experimental | Opt-in extension surface for third-party satellites. The in-process trust controls are friction, not a sandbox; the read-only role is the boundary. See [plugins](/guides/plugins) and the [security guide](/guides/security). |
 | Read-replica routing | Experimental | No automatic failover by design; use the retry-on-primary pattern in [read replicas](/guides/read-replicas). |
 | Audit logs | Experimental | Satellite (in core). |
 | Webhooks | Experimental | Satellite (in core). |

packages/core/.c8rc.json

@@ -15,8 +15,8 @@
   "report-dir": "./coverage",
   "clean": true,
   "check-coverage": true,
-  "lines": 64,
+  "lines": 65,
   "branches": 85,
   "functions": 75,
-  "statements": 64
+  "statements": 65
 }

packages/core/src/commands/commands.json

@@ -532,6 +532,19 @@
       "args": [],
       "options": { "startApp": false },
       "filePath": "health_check.js"
+    },
+    {
+      "commandName": "plugin:doctor",
+      "description": "Diagnose the installed plugin/satellite platform posture — ABI compatibility, native-addon sandbox risk, the TRUSTED_SATELLITES allowlist, and the read-only firewall",
+      "help": "",
+      "namespace": "plugin",
+      "aliases": [],
+      "flags": [
+        { "name": "json", "flagName": "json", "required": false, "type": "boolean", "description": "Emit a JSON report on stdout instead of the table" }
+      ],
+      "args": [],
+      "options": { "startApp": true },
+      "filePath": "plugin_doctor.js"
     }
   ],
   "version": 1

packages/core/src/commands/index.ts

@@ -34,4 +34,5 @@ export { default as TenantGdprAnonymize } from './tenant_gdpr_anonymize.js'
 export { default as TenantComplianceReport } from './tenant_compliance_report.js'
 export { default as TenantVectorProvision } from './tenant_vector_provision.js'
 export { default as HealthCheck } from './health_check.js'
+export { default as PluginDoctor } from './plugin_doctor.js'
 // The `tenant:billing:*` commands moved to `@adonisjs-lasagna/billing`.

packages/core/src/commands/plugin_doctor.ts

@@ -0,0 +1,78 @@
+import { BaseCommand, flags } from '@adonisjs/core/ace'
+import type { CommandOptions } from '@adonisjs/core/types/ace'
+import { getConfig } from '../config.js'
+import { discoverSatellites } from '../sdk/configure_kit.js'
+import { trustedSatellites } from '../sdk/plugin_env.js'
+import PluginDoctorService from '../services/plugin_doctor_service.js'
+import type { DiagnosisSeverity } from '../services/doctor/types.js'
+
+const SEVERITY_COLOR: Record<DiagnosisSeverity, 'cyan' | 'yellow' | 'red'> = {
+  info: 'cyan',
+  warn: 'yellow',
+  error: 'red',
+}
+
+/**
+ * `plugin:doctor` — diagnose the installed plugin/satellite PLATFORM posture (S6).
+ * It reads the discovered satellite manifests plus the runtime trust and firewall
+ * configuration and reports ABI drift, native-addon sandbox risk, a stale
+ * `TRUSTED_SATELLITES` allowlist, a missing read-only firewall, and which plugins
+ * hold declared (consent-gated) permissions. The checking logic is the pure `PluginDoctorService`;
+ * this command is the thin shell that gathers the input and renders the report.
+ *
+ * It does NOT re-check manifest↔spec coherence — that is the `check-plugin-permissions`
+ * CI guard's job (the specs are not available at runtime). Exit code 1 on any error.
+ */
+export default class PluginDoctor extends BaseCommand {
+  static readonly commandName = 'plugin:doctor'
+  static readonly description =
+    'Diagnose the installed plugin/satellite platform posture — ABI compatibility, ' +
+    'native-addon sandbox risk, the TRUSTED_SATELLITES allowlist, and the read-only firewall'
+  static readonly options: CommandOptions = { startApp: true }
+
+  @flags.boolean({
+    flagName: 'json',
+    default: false,
+    description: 'Emit a JSON report on stdout instead of the table',
+  })
+  declare json: boolean
+
+  async run() {
+    const root = this.app.makePath()
+    const discovered = await discoverSatellites(root, (m) => this.logger.warning(m))
+    const config = getConfig()
+
+    const report = new PluginDoctorService().run({
+      satellites: discovered.map((s) => ({
+        packageName: s.packageName,
+        name: s.manifest.name,
+        satelliteApi: s.manifest.satelliteApi,
+        permissions: s.manifest.permissions,
+        nativeAddons: s.manifest.nativeAddons,
+      })),
+      trusted: trustedSatellites(),
+      readOnlyConfigured: config.plugins?.readOnly !== undefined,
+    })
+
+    if (this.json) {
+      this.logger.log(JSON.stringify(report, null, 2))
+      this.exitCode = report.totals.error > 0 ? 1 : 0
+      return
+    }
+
+    this.logger.info(`${discovered.length} installed satellite(s) discovered`)
+    for (const issue of report.issues) {
+      const tag = this.colors[SEVERITY_COLOR[issue.severity]](`[${issue.severity.toUpperCase()}]`)
+      this.logger.log(`  ${tag} ${issue.message}`)
+    }
+    this.logger.log('')
+    this.logger.log(
+      this.colors.bold('Summary  ') +
+        `info: ${report.totals.info}  ` +
+        this.colors.yellow(`warn: ${report.totals.warn}`) +
+        '  ' +
+        this.colors.red(`error: ${report.totals.error}`)
+    )
+    this.exitCode = report.totals.error > 0 ? 1 : 0
+  }
+}

packages/core/src/isthmus/registry.ts

@@ -123,6 +123,22 @@ export const ISTHMUS_REGISTRY = [
     reviewed: '2026-07-08',
     nextReview: '2027-01-08',
   },
+  {
+    id: 'guard.plugin_extension_identifier',
+    pillar: 'guard',
+    bugClass: 'plugin-identifier-injection',
+    failMode: 'closed',
+    phase: 'runtime',
+    event: 'isthmus:guard:plugin_extension_identifier:rejected',
+    severity: 'high',
+    evidence: {
+      kind: 'inherent-risk',
+      ref: 'a plugin name, authorizer, capability key, or model name is minted from author input and interpolated into a Redis key, a Symbol, or DDL; a homoglyph or a colon must be rejected at the plugin surface, not folded onto an existing id',
+    },
+    guardFile: 'src/sdk/brands.ts',
+    reviewed: '2026-07-08',
+    nextReview: '2027-01-08',
+  },
   {
     id: 'guard.redirect_host',
     pillar: 'guard',

packages/core/src/sdk/brands.ts

@@ -1,17 +1,18 @@
-import { assertSafeIdentifier } from '../services/isolation/identifier.js'
+import { isSafeIdentifier } from '../services/isolation/identifier.js'
+import { emitIsthmusEvent } from '../isthmus/audit.js'
 
 /**
  * Nominal (branded) types for the plugin surface. A value of one of these types
- * is PROOF that it already passed {@link assertSafeIdentifier}: the ONLY way to
- * obtain one is through the smart constructor below, which runs the guard before
- * minting. So anything that later gets interpolated into a Redis key, a BullMQ
- * `jobId`, a `Symbol`, or raw DDL takes a branded parameter, and the compiler
- * refuses a raw `string` that skipped the check.
+ * is PROOF that it already passed the identifier guard ({@link isSafeIdentifier}):
+ * the ONLY way to obtain one is through the smart constructor below, which runs
+ * the guard before minting. So anything that later gets interpolated into a Redis
+ * key, a BullMQ `jobId`, a `Symbol`, or raw DDL takes a branded parameter, and the
+ * compiler refuses a raw `string` that skipped the check.
  *
  * The single `as` assertion in {@link mint} is the ONE sanctioned type assertion
  * on this surface (the plan's E1 rule bans casts everywhere else). It is safe
- * precisely because `assertSafeIdentifier` has already thrown on anything that is
- * not `/^[a-zA-Z0-9_-]{1,63}$/` in canonical NFKC form.
+ * precisely because `isSafeIdentifier` has already returned false — and `mint` has
+ * thrown — on anything that is not `/^[a-zA-Z0-9_-]{1,63}$/` in canonical NFKC form.
  *
  * These are IDENTIFIER slugs (a plugin's short registration name, an authorizer
  * name, a capability key), NOT npm package names — a package name like
@@ -36,13 +37,23 @@ export type CapabilityKey = Branded<'CapabilityKey'>
 export type ModelName = Branded<'ModelName'>
 
 /**
- * The one sanctioned assertion site. Runs the identifier guard (which THROWS on
- * anything unsafe, emitting `guard.tenant_identifier`) and only then mints the
- * brand. A dedicated `guard.plugin_extension_identifier` isthmus event is layered
- * on in the E3 hardening pass; today the shared identifier guard carries it.
+ * The one sanctioned assertion site. Validates the raw string with the shared
+ * identifier predicate and, on a reject, emits the dedicated plugin-surface guard
+ * `guard.plugin_extension_identifier` (distinct from the tenant-DDL
+ * `guard.tenant_identifier`, so an operator can tell a hostile plugin identifier
+ * apart from a bad tenant id) and throws BEFORE minting the brand. The single `as`
+ * below is reached only once the predicate has confirmed the value is safe (S6).
  */
 function mint<B extends string>(raw: string, kind: string): Branded<B> {
-  assertSafeIdentifier(raw, kind)
+  if (!isSafeIdentifier(raw)) {
+    emitIsthmusEvent('guard.plugin_extension_identifier', {
+      metadata: { kind, value: String(raw).slice(0, 64) },
+    })
+    throw new Error(
+      `Refusing to mint unsafe plugin ${kind} "${String(raw)}". ` +
+        `Names must match /^[a-zA-Z0-9_-]{1,63}$/ in canonical (NFKC) form.`
+    )
+  }
   return raw as Branded<B>
 }