Trust-boundary tracking for Grida. Every prevented vulnerability gets a stable id, the id appears in every file the boundary depends on, and this document is the central registry.
We use GRIDA-SEC-001, GRIDA-SEC-002, … as canonical ids for
security boundaries we have prevented. The format is deliberately
unlike CVE:
- A CVE describes a vulnerability that was discovered, often after exposure. The id implies "this was a problem."
- A GRIDA-SEC id describes a vulnerability that was structurally prevented from existing — and a contract with the codebase that it must stay prevented. The id is "this is a thing we keep safe."
Every GRIDA-SEC id has:
- An entry in this file with the threat model and the enforcement mechanism.
- A grep tag in every file bound by the contract — comments in source, callouts in READMEs, ingress filters in scripts.
- An auto-loaded skill (.agents/skills/security/SKILL.md) that triggers when an agent encounters the tag.
The grep is the index.
grep -r GRIDA-SEC-001 .returns every file in that contract.grep -r GRIDA-SEC .returns every security boundary in the repo.
Grida is open source. The threat model is public; the URLs an attacker might find are public; the fact that webhooks exist is public. Security in this repo is therefore structural, not secret. We make every boundary loud, named, and grep-able so that future work doesn't drift into opening new attack surface by accident.
A developer touching tagged code can't miss the marker; a code review of any tagged file naturally surfaces the others; an agent picks up the security skill the moment it sees "GRIDA-SEC" anywhere in context.
If you're adding a new boundary, allocate the next sequential id, add an entry below, and tag the relevant files. Don't reuse ids; don't renumber.
What it protects. Grida does not expose financial-provider callback receivers.
The retired /webhooks namespace returns 404 before browser, tenant or handler
processing. Do not reuse that namespace for an unauthenticated mutation.
Vulnerable scenario (prevented). An old callback path accidentally regains a handler or an authentication bypass during unrelated routing work.
How the code prevents it. The proxy rejects the entire retired namespace. Regression checks cover its root and child paths with read, write and preflight methods on an arbitrary host. They verify no handler pass-through or browser service loading.
Files bound by this id.
- editor/proxy.ts — rejects retired ingress.
- editor/lib/api/proxy.test.ts — ingress regression checks.
What it protects. The (insiders) route group remains a local developer
surface. /insiders/* is reachable only when NODE_ENV === "development".
Next server actions are HTTP RPC endpoints; hiding a harness link does not
prevent access to its actions. Never import insiders actions from production
routes, which would publish them under a different URL and bypass this gate.
How the code prevents it. editor/proxy.ts returns 404 for
/insiders and /insiders/* outside development, including action POSTs.
The insiders layout independently calls
notFound() outside development. Provider tunnels must not expose this group.
Retained history. The former /insiders/billing harness exercised privileged
financial lifecycle actions without org-membership checks. It was retired
with Grida's duplicate financial engine; Platform owns current financial QA.
Its deleted billing actions are not current proof or instructions. This ID
retains the threat model and governs every remaining insiders surface.
What does NOT belong under (insiders)/. Anything that needs to ship to
production. Move a graduating feature to its authenticated product/API surface;
never relax the insiders gate.
What it protects. Every call into the AI provider SDKs (Vercel AI
SDK, Replicate, OpenAI, Anthropic, and funded Tripo) is gated and billed against an
organizationId. If that id reaches the seam unverified, an attacker
who can choose the id drains another org's credit balance. The
boundary is the rule that every organizationId reaching
editor/lib/ai/server.ts has been verified as a member-org for the
calling user.
Vulnerable scenario (prevented). A developer adds a new AI route
handler that reads organizationId from the request body and forwards
it straight into the seam. An attacker enumerates organization_id
(sequential bigint) and submits requests with organizationId = <victim>. Each request spends the victim's credit and can deny their subsequent
AI work until the account is funded again. Worse, the attacker's free-tier user
enjoys the victim's credit for as long as it lasts. Mass automation makes this an
asymmetric DoS-by-billing attack.
Why it's specifically risky here. AI route handlers and server actions sit on internal/private surfaces, but they are still HTTP endpoints reachable by any authenticated user. Org membership on product data reads does not by itself authorize AI spending. GG obtains fresh shared-credit admission for migrated execution; retained native operations preserve source receipts. Explicit producer membership verification is still required. Without a structural producer-side rule, every new AI endpoint is a fresh chance to forget the membership check.
How the code prevents it.
- Verified organization producers —
editor/lib/auth/organization.ts
exports
requireOrganizationId({ user_id, request, routeParams, inputOrgId }). It resolves from: route param slug → request headerX-Grida-Organization-Id→ explicit input. Every resolved id is verified viaassertOrgMember(user_id, org_id)before return. No "current org" is read from session blob / cookie. GG execution instead consumes theorgclaim from the exclusively verified GRIDA-SEC-006 bearer. That grant was minted after authenticated membership verification; the documented token lifetime bounds this authority. Neither the GG 3D binding nor its execution seam reads an org from input, cookies, account headers or a provider upload reference. - Runtime contract in the seam —
editor/lib/ai/server.ts
withTransactionand the trusted GG adapter validate organization identity; native calls throwMissingOrgIdErroriforganizationIdis missing, non-integer, or non-positive. This is unconditional on the billed path: the formerNEXT_PUBLIC_GRIDA_LOCALDEV_SUPERUSERexception (syntheticorganizationId:0, gate/ingest/auth skip) has been removed — no code path skips this check while billing. The only intentional bypass is the BYOK carve-out below, and it does not bill. - One billing seam, explicit provider-import owners —
editor/lib/ai/server.ts owns the selected Grida execution entry point; GG owns migrated provider
dispatch/metering and Platform owns shared financial billing. Retained native
operations use Grida source admission/receipt integration;
value imports of
replicate,openai,@ai-sdk/*,@anthropic-ai/sdkand the portable@grida/aiexecution SDK are restricted to the reviewed seam allowlist. The exact@grida/ai/catalogueand@grida/ai/discoverymetadata entries are allowed independently: neither executes inference or acquires credentials. Enforced by oxlintno-restricted-imports(editor/.oxlintrc.jsonc) and the CI audit script (editor/scripts/audit-ai-seam.ts). A new file that bypasses the seam fails at lint or CI. The trusted GG adapter uses a distinct server workload secret, canonical organization and feature. Its receiver checks current credential authority and organization existence; Grida must verify user membership before sending the assertion. Browser cookies and personal API keys cannot substitute for this credential. All generation/metering stays in GG; there is no direct-provider fallback or duplicate native receipt. - 3D upload ownership and result custody — the named
3D adapter retains only free Tripo presign
preparation with server-only
GG_TRIPO_API_KEY. Its key must belong to the same provider account as GG. Authenticated caller/org-bound signed upload tickets are verified before forwarding an internal typed file reference; ordinary users cannot claim a provider file token or arbitrary input URL. GG owns paid model generation, checking, rigging, durable observation and settlement. Grida validates/downloads product output using its pinned public HTTPS transport, without provider credentials, redirects or private DNS destinations. An asset failure does not regenerate, refund known cost or issue a second native receipt. Already accepted pre-transition work keeps its original source recovery obligation; KI-BILL-005 preserves that historical distinction.
BYOK carve-out (intentional). When a contributor sets a BYOK_*
key (editor/lib/ai/models.ts —
BYOK_OPENROUTER_API_KEY, BYOK_VERCEL_AI_GATEWAY_API_KEY), grida/model
return a bare provider so the AI-SDK text/chat path bypasses
the billing seam: no Platform admission or charged usage delivery, and the
MissingOrgIdError runtime contract above does not fire (a bare
provider has no middleware). The contributor's own provider key is
charged directly — there is no Grida balance, hence no victim to
drain, so the billing trust boundary is moot for that path. Scope —
AI-SDK path only. BYOK only swaps the AI-SDK provider; Replicate-
backed actions (runPrediction/withTransaction — audio, image) are
not bypassed and still gate + ingest under BYOK. Accordingly the
withAiAuth balanceCents:0 short-circuit is opt-gated
(byokBypass, default false): only AI-SDK actions set it, so billed
actions still read the real balance and cannot silently drain credit
while reporting 0. BYOK bypasses billing only — never auth. requireOrganizationId and
route/action auth always run, so a logged-in user with no resolvable
org is still rejected. Gated solely by server-only, non-NEXT_PUBLIC_
env vars never set in the hosted product (same trust model as other
server-only credentials). Fail-closed: byok is
null unless a key env var is a non-empty string, so any ambiguity
falls back to the billed path. Residual risk: byok is resolved
once at module load with no per-request guard — an accidental BYOK_*
on a hosted/preview deploy would make every org bypass billing and the
org-id sanity gate (auth still holds). Acceptable only because it is a
contributor/self-host switch under the existing server-env trust model.
Funded provider authority. Migrated generation uses the server-only GG product workload configuration.
The retained Library Vercel embedding provider reads only
GG_VERCEL_AI_GATEWAY_API_KEY for an explicit API key. An absent or blank value
retains the SDK's per-request platform OIDC resolution; an explicit empty SDK
setting prevents its ambient AI_GATEWAY_API_KEY lookup. Replicate predictions
require a nonblank GG_REPLICATE_API_TOKEN at execution, with no legacy token
fallback. Contributor overrides never supply these funded clients. Library query
embeddings still use the shared provider without user billing (or the contributor
override locally), and OpenAI model listing keeps its separate OPENAI_API_KEY.
Native CLI/Desktop credential names and stored provider IDs are independent of
this server configuration.
Files bound by this id. Run grep -rn GRIDA-SEC-003 . to enumerate.
Today:
- editor/lib/auth/organization.ts —
requireOrganizationId. - editor/lib/ai/server.ts — single seam entry; unconditional runtime gate; BYOK layer switch.
- editor/lib/ai/models.ts — contributor BYOK and explicit funded Vercel AI Gateway/OIDC authority.
- Provider credential tests and Replicate credential tests — funding-role separation, per-request OIDC, missing credentials and preserved billing.
- GG Tripo execution and billing contract tests — verified org input, unconditional gate, infrastructure-key-only execution and actual receipts.
- GG Tripo egress and transport tests — fixed API/asset authority, public DNS pinning, verified TLS and no credential-bearing redirects.
- editor/.oxlintrc.jsonc — import lint rule.
- editor/scripts/audit-ai-seam.ts — CI audit.
What does NOT belong here. Reading organizationId directly off a
request body in any AI-adjacent code. Even if you think you "trust"
the body — Next.js server-action hashes ship in the client bundle and
become public the moment they're shipped. Always go through
requireOrganizationId or the exclusively verified, membership-derived GG
claims described above. An upload ticket is never organization authority.
What it protects. Grida Desktop supervises a native Rust chat host and a
retained daemon sidecar. The native host owns new chat sessions and agent
execution. The Node sidecar retains local file paths, workspaces, media,
provider settings and shared credential adapters. Native-provider OAuth has its
separate credential boundary (GRIDA-SEC-008). The TypeScript chat composition
has been removed.
Electron main listens on an ephemeral
127.0.0.1 port and transfers only accepted connected sockets to the
socketless sidecar, whose authenticated daemon protocol is the canonical local
capability surface for the renderer. If anything other than the legitimate
Electron renderer reaches it — another browser tab on grida.co, a
local malware process, a same-origin XSS payload — that party can
exfiltrate secrets, read/write the user's files, and bill AI calls.
The boundary is the rule that only requests originating from the
desktop's privileged renderer at a /desktop/* path, signed with
the per-spawn Basic Auth token, may reach the daemon, and only the
main-owned provider transport may carry the daemon's provider HTTP outside
its sandbox. Electron main owns the exact loopback listener; ServicesSidecar
receives no listener, and the macOS/Linux sandbox grants it no generic
bind/connect authority. Windows does not yet satisfy that containment
clause; its current nonconformance is recorded below.
Package shape. The perimeter and the host capability routes
(files, recents, workspaces, the secrets store) are owned by
packages/grida-daemon (@grida/daemon —
DaemonServer, http/auth.ts, http/origin.ts, http/server.ts).
The media/provider HTTP adapters are mounted behind that perimeter through
the typed DaemonTenant seam and ship in
packages/grida-ai-host. Its separate
@grida/ai-host/media-server entry starts the media routes, BYOK configuration
and scoped GG custody; the package contains no chat runtime, chat SQLite state,
skills or ACP. On macOS/Linux, provider access lazily opens only the shared
credential owner's SQLite exclusion lock (GRIDA-SEC-014). Windows retains the
host-local credential backend described in that entry. Chat enforcement
belongs to the Rust host and native process contracts.
Desktop selects the composition before importing the server. A media-only
launch does not construct a command executor or enable native ChatGPT OAuth. It retains the same main-owned
listener, authenticated perimeter, provider transport and media root. The
choice is explicit host configuration, never an automatic fallback after
agent initialization fails. No second daemon or credential store is created:
the daemon-owned OAuth AuthStore remains separate from the shared provider
TOML owner, with one memory-only GG session and one catalogue per composition.
The first provider access retires legacy API entries through GRIDA-SEC-014;
subsequent reads never use that retired source.
The supervisor loads its native sandbox before spawning the child. On macOS and Linux an unavailable sandbox refuses the launch; Windows keeps its explicitly unconfined non-agent services.
Shared image, video, audio and 3D operations and provider HTTP belong to
@grida/ai. The tenant supplies narrow key/token
readers and the same host-authorized transport; host adapters retain request admission,
workspace reads, media persistence, and optional chat lifecycle. The SDK does not mount
a route or create a daemon. Extracting an operation grants no additional network
or filesystem authority.
Vulnerable scenario (prevented). A stored XSS lands on a marketing
page or blog post served from grida.co. The user has the desktop app
open. Without the boundary, the XSS calls
fetch('http://127.0.0.1:<port>/secrets/get?key=byok.openrouter') and
ships the key to an attacker-controlled host; or
fetch('http://127.0.0.1:<port>/files/read?docId=…') and exfiltrates
the user's design files. A parallel local-machine attack: an
unprivileged malware process scans 127.0.0.1:49152-65535, finds
the daemon, and hits its endpoints (a non-browser client doesn't honor
Origin checks). Both attacks defeat the "secrets in keychain"
intuition because the local network is a trust shortcut.
Why it's specifically risky here. The desktop V1 renderer URL-loads
https://grida.co/desktop/... (a literal path, distinct from the
universal-routing /_/... system).
That puts the privileged preload bridge on the same Chromium origin
as every other grida.co page. Without per-path preload scoping and
per-request agent-server auth, "XSS on grida.co" becomes "RCE-equivalent in
the desktop app" (the same failure class as the Discord 2021 Sketchfab
embed → context-isolation-disabled → RCE chain). Industry precedent
(Figma's FigmaAgent allowlisting only figma.com + Local Network
Access permission) confirms the threat is real and the mitigation
shape is standard.
How the code prevents it. Composed of mutually reinforcing controls; any single control is insufficient.
-
Path-scoped preload — the bridge in desktop/src/preload.ts installs
window.gridaonly whenlocation.pathnameis/desktopor starts with/desktop/at preload-run time. The preload fails closed when the current document is not a desktop route. Electron preload is the sole bridge installer. Desktop renderer code reads the bridge through its typed client. A fresh document load that doesn't match the prefix gets no bridge, so XSS on/blog/foocannot see it. SPA navigation within an already-loaded document is constrained by preload's history guard and thewill-navigate/did-navigate-in-pageallowlist indesktop/src/window.ts—contextBridge.exposeInMainWorldhas no revocation API, so the navigation guards defend the post-mount surface. Path eligibility is not capability admission by itself:desktop/src/main/desktop-entry-window.tsresolves an exact sender window to its current native role only while that role is stable, anddesktop/src/main/ipc-admission.tsapplies a closed role + pathname + channel policy inside the common guarded-IPC wrapper. Main rejects auth and onboarding paths even before a navigation observer runs; sign-in receives only browser launch + read-only title-bar state. Onboarding receives only ChatGPT controls, completion, and two purpose-scoped main-owned workspace operations (read the default or choose/register one folder). It never receives the daemon connection tuple or a generic filesystem dialog. A transitioning, stale, foreign, or post-sign-out auxiliary renderer resolves to no role and receives no IPC capability. -
CSP-strict
/desktop/*routes —editor/proxy.tssets a per-request nonce-based CSP on every/desktop/*response, following the canonical Next.js pattern (nonce +'strict-dynamic'). Concretely:default-src 'self'; script-src 'self' 'nonce-<random>' 'strict-dynamic' 'wasm-unsafe-eval'; connect-src 'self' http://127.0.0.1:* http://localhost:*. The nonce is generated in the proxy, exposed to SSR via thex-noncerequest header, and Next.js attaches it to its own framework scripts automatically. No third-party analytics, Sentry, or marketing scripts run on these routes — eliminates the "Sentry input masking is fragile" exfil for BYOK keys. We chose nonce +'strict-dynamic'over'unsafe-inline'because/desktop/*was already dynamic-rendered (bridge gate is client-only) — the dynamic-rendering cost most Next.js teams pay for nonce CSP is a cost we already pay, so this control stays load-bearing at zero additional maintenance.For maintainers: if you add inline scripts to a
/desktop/*layout or page, they must carry the nonce. Read it via(await headers()).get("x-nonce")and pass it to whatever you're rendering (e.g.<ThemeProvider nonce={nonce}>fornext-themes,<Script nonce={nonce}>fornext/script). Next.js handles framework scripts and<Script>components automatically when theContent-Security-Policyheader is present on the request. Inline<script>tags written by hand are your responsibility. -
Per-request Basic Auth — the daemon rejects any request without
Authorization: Basic <base64("agent:<password>")>. Password is a random 256-bit value generated per sidecar spawn. Electron main sends it in the private, versioned stdin bootstrap frame and serves it to preload only through guarded IPC; it is never placed on argv, env, disk, orwindow.grida.Electron main owns the exact
127.0.0.1:<ephemeral>listener. Each loopback connection is accepted paused and transferred as an already-connected socket over the per-spawn Node IPC descriptor. ServicesSidecar startsDaemonServerwithout a listener and can serve only that transferred connection: it receives no listener, destination field, bind operation, or connect operation. The descriptor is therefore a socket capability channel, not a second daemon protocol. This keeps socket creation denied in the sidecar's native profile and preserves the main-owned loopback port across Bubblewrap's private Linux network namespace.Authenticated liveness and header-only credential. Liveness probing is the authenticated
/handshake; there is deliberately no unauthenticated health route for local malware to port-scan against. TheAuthorization: Basicheader is the only credential carriage:@grida/daemon'shttp/auth.tsnever reads a credential from the query string, and theDaemonTenantseam offers no way for a tenant to declare one. A credential in a URL can land in logs and history, so adding a query carriage for any route is a change to this contract. -
Defense-in-depth
Referercheck — the daemon rejects any request whoseRefererpath is not under the host-declared desktop route root. Catches a same-origin XSS that somehow bypasses preload scoping (e.g. a future SPA-nav race condition). -
secrets.getdoes not exist — the bridge surface in desktop/src/preload.ts exposes onlysecrets.has/set/delete. The media tenant reads keys internally when calling the BYOK provider; key material never returns to renderer. Closes the exfil path even if all preceding controls were bypassed. -
Host-routed provider HTTP —
@grida/ai-hostcomposes@grida/ai's two explicit, construction-time HTTP operations: authenticated provider requests and credential-free provider-asset downloads. Desktop implements them over the sidecar's inherited stdin/stdout using a strict length-prefixed protocol; stdout is protocol-only and stderr is logs. Desktop's sidecar requires both operations before it selects any daemon composition. Electron main executes requests through a dedicated, non-persistent ChromiumSessionin system-proxy mode. It revalidates the host-issued grant, method, exact/suffix origin, headers, body bounds, and every redirect; response bytes move only against explicit credit and aborts propagate both ways. The download lane contains only enumerated provider-owned namespaces — there is no arbitrary public-URL grant. There is no renderer broker method, loopback proxy, socket path, or environment credential. The ChatGPT-subscription grant registered by GRIDA-SEC-008 holds only exactauth.openai.comtoken andchatgpt.comResponses destinations. It is a Main-only grant: Main dispatches it for its native subscription host, it is never published to the sidecar, and it is never eligible for the asset lane. When this transport is enabled, the outer native policy omits BYOK/GG destinations, so missing provider wiring cannot fall back to direct sidecar egress. Electron main transiently observes provider request headers and bodies while transporting them, but never persists, returns, or logs credentials or bodies; credential ownership and injection remain in the sidecar's provider layer.Anonymous GG discovery has a separate, narrow permission: credential-free
GETrequests to exactlyhttps://gateway.grida.ai/v1/models,/v1/endpointsand/schemas/operations.json, with no query or body and onlyAccept,Accept-EncodingandUser-Agentheaders. It grants no inference endpoint, alternate port, subdomain or download authority. The network policy and tests enforce that permission; the discovery reader bounds metadata bytes, deadlines and cache age. Public metadata never carries a scoped token or authorizes spending. Signed-in execution continues through the configured Grida API origin; its JWT never goes to public GG discovery or asset hosts.Chromium supplies the operating system's effective proxy/PAC, VPN, DNS, and platform-trust behavior. Cached or integrated proxy authentication remains eligible; Desktop does not collect proxy usernames/passwords, so an interactive proxy challenge fails closed with a specific diagnostic. This is route compatibility, not a censorship-circumvention tunnel: no route is created when Chromium and the operating system have none.
Endpoint providers (local LLMs). The
media composition serves
/providers/endpoints/* — CRUD over user-configured OpenAI-compatible
endpoints (Ollama preset, self-hosted gateways), persisted at
${userData}/endpoints.json — only when the host opts in with
endpoint_settings. The routes use the media tenant's provider transport,
store, and credential allowlist; they grant no local CLI discovery. The split
that keeps the secrets
discipline intact: an endpoint config (base URL + registered model list) is
plain readable config the renderer may list back, while an endpoint's
optional API key rides the /secrets/* surface under the endpoint's
id (the secrets-route allowlist admits configured endpoint ids) and is
never readable. The config validator
(packages/grida-ai-host/src/protocol/endpoints.ts) pins the shape —
http(s) URL with no URL userinfo, bounded sizes, unknown fields dropped — so a
config write cannot smuggle credentials or blobs into the readable store.
base_url is user-owned egress by design, but renderer configuration is not
network authority: Desktop routes set/delete/probe through guarded main IPC
from the exact Settings main frame. Explicit Connect/Save is consent for the
displayed endpoint; no additional native dialog is required. Main saves a
separate owner-only receipt at ${desktopUserData}/provider-authority/consent.json,
bound to the endpoint ID and full canonical base URL. The entire receipt
directory is denied to the retained sidecar and excluded from file/workspace
admission; native commands already exclude the browser profile. The
sidecar-writable endpoints.json file cannot mint or change this authority.
This policy trusts the first-party Settings renderer to invoke Save only for
an explicit Connect/Save action. IPC admission proves the contained Settings
frame and current authenticated role; it does not prove a physical user gesture
or protect against a compromised trusted Settings renderer invoking Save.
Receipt reads are bounded and reject symlinks, hard links, unsafe ownership or
permissions, malformed documents and unknown versions. Windows retains the
existing inherited browser-directory ACL contract, without a POSIX privacy claim. Only localhost, subdomains
of .localhost, and IP literals are currently eligible, always as exact
origins. Remote hostnames — including .local names — remain withheld because
the current Chromium connector cannot atomically bind proxy/PAC selection and
DNS resolution to one authorization decision. Existing configured endpoints
restore without dialogs only when the current config matches Main's receipt
and the route remains eligible. Missing consent, an externally changed URL,
or a malformed receipt stays unavailable until explicit Connect/Save. Before
every service bootstrap, Main suspends custom grants, then restores matching
config/receipt bindings before exposing readiness. Unchanged bindings retain
their IDs across sidecar crashes so live native chats keep their captured
network; a fresh Main process mints fresh capability IDs. Changed or removed
bindings are discarded. Changing or deleting an endpoint revokes its old live
and durable authorization before replacing/removing config. Grant publication
and revocation still await the sidecar ACK; failure retires that generation.
Per-ID queues cover Save, Delete, discovery metadata and restore, with
generation and Settings-frame rechecks after asynchronous work. A late probe
or refresh cannot recreate deleted config. The optional
endpoint_authorization read and update_endpoint_models operation consume
existing authorization only. Metadata merges detection-owned fields into
current models and preserves human overrides, defaults and other settings.
Probes require the same exact saved consent and never mint temporary grants. The routes sit
behind the same CORS/Referer/Basic-Auth stack as everything else. The
/providers/endpoints/probe route makes the host GET a
user-supplied URL's model listing (the renderer's grida.co origin cannot
reach a local Ollama itself) — the same egress a configured run already
performs; responses are parsed and reduced to
{id, tool_call, contextWindow} rows with bounded reads (timeout + size
cap), never proxied raw. The host transport permits an eligible local endpoint
only through that explicit exact-origin grant; it does not turn endpoint
config into a generic proxy.
External agents. The TypeScript daemon contains no chat execution, model resolver, or external-agent subprocess activation; its tenant serves media operations and provider settings only. Native Local agent execution uses its own reviewed profile and process confinement described below.
Electron-side hardening (mandatory; see the
Electron security checklist).
contextIsolation: true, nodeIntegration: false, sandbox: true,
webSecurity: true, allowRunningInsecureContent: false; release builds
load https://grida.co while dev loads http://localhost:3000;
will-navigate blocks navigation off EDITOR_BASE_URL;
setWindowOpenHandler denies and routes external links through
shell.openExternal after validation; will-attach-webview rejects;
every main-process IPC handler validates event.senderFrame.url.
Explicit Full access. The ordinary restricted profile retains all command and filesystem exclusions below. A trusted launch can separately opt into Full access, and Desktop Main requires an in-app confirmation for the exact attached chat before selecting it. The private, negotiated permission-mode operation is not a model tool. The host records the per-chat selection and captures it with accepted work; another chat and newly created chats remain restricted. Changes require an idle chat, an empty queue and no running command process. Workers inherit their assignment's captured posture.
Full access deliberately removes model-command filesystem, network and IPC confinement. Same-user code can read or modify local credentials, Grida state, installed files and other same-user processes wherever OS permissions allow. Private file modes and cleared environments do not isolate these resources from that code. The command-level exclusions in GRIDA-SEC-004 and GRIDA-SEC-014 therefore apply to restricted execution, not this explicit posture. The renderer bridge, retained-sidecar sandbox and purpose-bound provider transport remain in force; none is widened to provide the escape hatch. Full access adds no OS privilege elevation or automatic credential injection and does not require automatic approval review.
The native helper provides process ownership, input/output bounds, terminal interaction, deadlines and best-effort cleanup for unconfined launches. Its evidence identifies the unconfined backend and cannot claim filesystem, destination, hostile-process isolation or Linux PID-namespace termination. Detached descendants may survive. Restricted setup failure still refuses the launch and never selects this path. Host-owned reviewed checks retain their confined execution scope.
Native command adapter (restricted profile). A host can construct the adapter for one
authorized execution scope after probing the installed native sandbox. A model
command runs as <shell> -c <cmd> in the user's named POSIX shell: the
captured environment's SHELL only when it is an absolute path to an
executable sh, bash, zsh or dash, otherwise /bin/sh. The call
supplies the command line, an optional working directory and a terminal
choice; it supplies no environment values or stdin. A command still running
when its wait ends is kept by its chat in the host's process store. Turn end,
cancellation, pause and approval waits leave it running; it ends when the
model or a person stops it, it is evicted for a newer process (64 per chat),
its chat is deleted, or the host shuts down. Kept processes run under a
24-hour scope. A changed permission profile applies to later launches; it
does not stop a process that is already running. Input written to a terminal process
after launch is covered by the launch approval and is not separately
reviewed, so a policy that must see every command should refuse interactive
terminals. Cleanup that cannot be verified is reported at host shutdown
rather than holding the queue. Filesystem grants, network denial, private
temporary storage, and the termination guarantee come from the host and
native sandbox.
A host profile can let programs read and execute anywhere except its protected
paths (disk read) and start from the host's environment minus Grida's own
GRIDA_* variables and the provider credential variable the host was launched
with. The host's state, the profile file, the credential home,
GRIDA_HOME and ~/.grida stay read-and-write protected, so disk read never
reaches them; the sandbox expresses each as an exclusion of every grant rather
than relying on rule order. Version-control and agent metadata (.git,
.agents, .grida, .codex, .aws) directly under a writable root stay
read-only once it exists when the command starts; agent configuration
(.grida, .codex) is protected even before it exists. On Linux the sandbox
holds an empty, read-only placeholder directory at such a missing path for the
command and removes it after a verified end, since bubblewrap can only carve
out a path that exists. A command can therefore initialize a new repository,
and the next command cannot change it.
A command that may write the project may also write the shared /tmp, as the
policy's workspace-write level allows; the host's stores never live there,
and a profile allowing such commands is refused unless its private temporary
parent lies outside /tmp (Desktop keeps it in /var/tmp on Linux).
A protected path inside a granted location is carved out of it; one
that contains a location granting what it denies still refuses the scope. Platform services
toolchains need (system information, the user database, the per-user cache
and temporary directory lookup, logging, certificate trust, semaphores,
pseudo-terminals, and resolving top-level links such as /tmp) are allowed;
they grant no file contents or network access. The
permission policy owns these defaults.
Restricted native text writes and edits run in the trusted host, not the sandbox, so they enforce the same boundary themselves. A write needs a current write grant, bound only after the profile's write rule admitted that exact action. The path is relative with normal components only; each folder is walked beneath the pinned root with symlinks refused and the device checked against the root, and the final folder is verified to still be inside the root. Missing folders are created beneath it. Version-control and agent metadata names are refused as the first component. Content goes to an exclusive temporary file in the same folder and is renamed into place; an edit also confirms the file is unchanged since it was read. Desktop grants the Default preset's write rule only for the selected project folder and registers no additional folders, so its file tools stay inside the project, apart from the settings file below, and no folder can be granted on request. Desktop supplies programs its captured login-shell environment, minus app variables. Preparation refusals share one tool response regardless of path existence.
Agent settings file. The host's own state stays protected, with one
carve-out: the file tools reach the host's settings file, config.toml in its
configuration folder (Desktop: the workspace's folder under chats/workspaces/;
headless: the state directory), as directory agent-settings. Nothing else
in that folder is reachable: list, search, image and other paths are refused,
and a launch profile cannot name a folder agent-settings. Under restricted access, a read runs under
the turn's file grant. Every write or edit is an approval request bound to that
exact action; the fixed ask rule ignores the folder rules, so neither the
Default preset's project write rule nor an earlier approval covers it, Plan
withholds it, and the automatic reviewer answers reads only. The host offers
the carve-out only while its command denials cover that folder for read and
write, so a command can neither read nor change the file the file tools
approve. The settings owner, not the workspace walker, performs the write: it
validates the complete result first, refuses invalid content unchanged with
its diagnostic, publishes owner-only content atomically under the writer lock,
refuses a concurrent manual edit, and activates the result for later accepted
input; accepted work keeps its capture. Desktop Main admits a write review
only for config.toml under the canonical settings folder it launched.
The schema accepts only schema_version and context.max_input_tokens, so an
approved write cannot add grants, protected paths, credentials, commands or
egress.
The adapter retains supervision after the runtime cancels an invocation. The
host's cleanup barrier reports pending or unverified command identities before
the host releases resources that depend on cleanup. Same-process reconciliation
matches the invocation and attempt against retained evidence. A missing match
leaves the result uncertain.
The retained sidecar starts no chat runtime and receives no command executor. Native command execution belongs to the Rust host and its scoped sandbox helper. The captured permission profile constrains the exact working directory, grants, protected paths, temporary scope, deadline and cancellation. The master keeps action admission, suspension and final accounting separate from the provider transport. See the native command owner and native sandbox.
The TypeScript command execution and its SRT worker were removed. Retained file/media services use a separate native Seatbelt or bubblewrap/seccomp launch; they receive no model command executor.
The current macOS retained-service profile permits metadata only on exact protected roots and their ancestors, so registry admission can revalidate their canonical identities. Protected contents, directory listings, extended attributes and other descendant metadata remain denied. Actual native tests exercise fresh managed-workspace creation alongside protected-root rejection.
- Process sessions (native confinement). A
native process session
runs a prepared command under the same scope without the finite wall-clock
limit; the scope deadline, cancellation, a stop request and dropping its
handle still end it. The trusted helper
uses the owner's end of its private status channel as a control channel for
interrupt and stop. End of stream or any unknown byte ends everything the
helper launched: on macOS the payload (a terminal payload's own group), the
rest of the payload's session and then the launcher group; on Linux the helper's exit as the PID namespace's
first process. A session or finite command therefore does not outlive an
owner that disappears. Interrupts reach the payload only through the helper.
A terminal session allocates its pseudo-terminal inside the sandbox through
the existing Seatbelt pseudo-terminal allowance or bubblewrap's private
/dev; sessions add no profile or syscall-filter rule. On macOS a terminal payload leads a session outside the launcher group. The helper signals it only while it is unreaped, then ends every remaining process of the payload's session, including job-control groups, and confirms that in its report only when none remains; otherwise the cleanup evidence is unverified. On macOS, a descendant that starts a session of its own can outlive a stop; Linux keeps the PID-namespace guarantee. Native sandbox tests cover retained output, terminal input, interrupts, stop with background descendants, the scope deadline, handle drop and owner loss. - Network (retained service, native confinement). On macOS and Linux the
retained file/media sidecar runs under native Seatbelt or bubblewrap/seccomp
confinement with no direct network: its profile has an empty domain
allowlist and denylist, and local binding is off. Construction refuses any
other network posture (
retained_service_direct_network_forbidden), and on Linux the syscall filter also denies new sockets. The daemon remains reachable because Electron main owns the exact-127.0.0.1loopback listener and transfers only accepted connected sockets, and provider HTTP for media and subscription work flows through main's provider transport over inherited channels. The retained process therefore has no network owner of its own. Windows retained services run without kernel confinement and receive no model command executor.
Human terminal (deliberate contrast to the agent shell). The
workbench's Terminal pane (bridge.terminal.*) is a real, unsandboxed
login PTY — arbitrary code execution by design, accepted under the same
trust model as VSCode's integrated terminal: the human runs commands as
themselves, on their own machine, with their own privileges (no
escalation). It is deliberately NOT wrapped in an agent sandbox and
deliberately NOT part of the agent's tool surface — the agent's Default command tool
stays confined by the native command sandbox, explicit Full access uses its
separate owned unconfined process path, and no code path hands the
agent a handle to a human terminal. What makes the surface acceptable is that
only the legitimate desktop renderer can reach it: the four terminal IPC
channels are registered through the same sender-frame guarded() wrapper
as every other native capability (editor origin + /desktop/* path), the
preload exposes them only on desktop routes, and the PTY host
(desktop/src/main/terminal-host.ts) additionally (a) resolves the spawn
cwd from a workspace id through the sidecar registry — the renderer
never passes a raw path, (b) binds each terminal to the WebContents that
created it so one window cannot drive another window's shell, (c) caps
PTYs per window, and (d) kills every PTY on window close and app quit.
A contract test (desktop/src/main/terminal-host.test.ts) fails if a
terminal channel is ever registered outside guarded().
Hosted auth + hosted AI. The desktop signs the webview into a
first-class Supabase cookie session via the system browser + PKCE +
grida://auth/callback deep link — that flow is its own boundary,
GRIDA-SEC-005 below. The hosted "included" AI provider — Grida
Gateway (GG), the gg provider, GRIDA-SEC-006 — amends the old
"sidecar holds no cloud credentials" invariant to its precise form:
the sidecar may hold ONLY the purpose-scoped, short-lived AI token
(memory-only, pushed by the renderer over /auth/gg/set, never
auth.json, never a refresh token) — the durable session stays in the
webview cookie jar. Files registered under this record for that work
(all marked GRIDA-GG):
packages/grida-ai-host/src/providers/gg-session.ts,
packages/grida-ai/src/{gg-session,music-client}.ts,
src/http/routes/gg-auth.ts, and the gg arms in
src/providers/{resolve-image,resolve-video}.ts. Electron main transports GG requests and can
transiently observe the scoped bearer header, but does not retain, persist,
return, or log it; steady-state token custody remains in the sidecar.
Entitlement enforcement stays server-side (the hosted endpoints gate + meter).
Update channel. Release builds must be signed/notarized by platform policy. Security-sensitive runtime deps are reviewed as part of the desktop release checklist; do not treat broad semver ranges as acceptable for code running inside this boundary without an explicit review note.
Workspace media streaming. The desktop media viewer renders
workspace images/videos from a custom privileged scheme,
grida-workspace://workspace/<workspaceId>/<relPath>, instead of inlining
bytes as base64 (which capped the viewer at 1 MiB). This adds a new
renderer-reachable file-read origin, so it is recorded here. The trust
model keeps the boundary intact. On compatibility profiles, Main proxies the
request to the sidecar's streamed GET /workspaces/file route with private
Basic Auth and the original Range header. The sidecar applies its workspace
file containment checks. On the qualified packaged native profile, Main
captures the exact directory identity during trusted workspace open, confirms
it still matches a current workspace registration and admits one read-only
worker under Seatbelt. The worker validates the directory identity, protected
roots and descriptor containment. Missing or changed admission ends the
request before any compatibility proxy. The renderer builds the URL as a pure
string (no credential crosses into it), and CSP scopes the scheme to
img-src/media-src only — it is not registered bypassCSP. A constant
host (workspace) carries no data so standard-URL host canonicalization can't
corrupt the id; both ids live in the path.
First-party library images (reference-first artwork). The artwork-station
gather step (design_search) shows the user images from the Grida Library,
and the picked references are kept as URLs and rendered directly (never
downloaded). The desktop CSP allows the selected first-party Library origin in
img-src only. Supabase (NEXT_PUBLIC_SUPABASE_URL) remains the default;
NEXT_PUBLIC_GRIDA_LIBRARY_STORAGE_PROVIDER=tigris explicitly selects the
Tigris asset origin and retains the configured Supabase image origin for saved
references. This is distinct from the generated-media rule above: generation
provider CDNs (fal/openrouter/…) stay excluded — generated media is sidecar
bytes via data:/blob:/grida-workspace:. Origins are fixed from the explicit
provider configuration at module load; an unset Supabase origin is omitted,
and malformed values cannot widen the policy.
proxy.test.ts pins both the allow (library origin in img-src only) and the
deny (provider CDNs still excluded). The alternative — proxying library images
through grida-workspace: like generated media — was rejected: the library is
first-party public read-only storage, and the product keeps its pins as URLs.
For a native workbench chat attachment, the Library selection action requires an authenticated catalog UUID and reads its exact first-party bucket object with bounded size and time, without redirects. It checks the catalog metadata and recorded digest when available. The renderer encodes only those returned bytes as a bounded PNG and submits it through the existing native image intake. This selection grants no provider URL or filesystem access.
Auto-created projects (managed root). The reference-first home lets a
newcomer start without choosing a folder: it posts to POST /workspaces/create,
which mints a new empty project directory (just the folder — no .canvas,
no manifest, no document of any kind). This adds a new renderer-reachable
write authority (previously the renderer could only register a folder the
user had already picked through the OS dialog), so it is recorded here. The
boundary holds by three rules, none of which trust the caller for a path: (a)
the managed root is host-injected — the supervisor passes
--projects-root=<~/Documents/Grida Projects> (desktop/src/main/services-sidecar-supervisor.ts),
never derived from the request; a host that wired no root refuses with a 400.
(b) The request's name is slugified to a single filesystem segment
(WorkspaceRegistry.createProject / slugifyProjectName): path separators,
.., NUL, and control chars cannot survive, so it can never be a path. (c) The
minted directory's realpath is asserted strictly under the managed root via
the shared containsPath (path-contains.ts — the same prefix+sep discipline
as the media store's containment asserts); an escape is removed and rejected. There is
no seed field anymore: the route body is { name? } only, and the
registry writes nothing but the directory, so the earlier manifest-injection
surface is removed outright rather than field-constrained — whatever document
the workspace eventually holds is created by the AGENT through its own
already-bound (and separately-gated) fs write capability, not by this route.
The retained sidecar's structured fs writes remain inside its coarse native
profile. A created project becomes an in-process workspace root for structured
tools. Native model commands receive their exact permission scope through the
Rust host and sandbox helper, independently of these retained service roots.
workspaces.create.test.ts pins traversal-name containment,
that the created project is empty (an unexpected seed body is inert), and the
no-managed-root refusal.
The private network host establishes bootstrap and control before provider-network initialization. Only an authorized provider request starts the memory-only Chromium session; it still waits for successful system-proxy configuration. Cancellation and shutdown settle pending requests without dispatch. After that wait, the host rechecks the exact current destination grant before Chromium receives the request. Initialization failure has no direct-network fallback. Boundary tests cover delayed/failed setup, revoked grants and late completion after shutdown.
The account owner reports scoped Gateway mint unavailability through a typed, credential-free failure. The chat IPC owner exposes only its fixed readiness state through one status channel; there is no separate availability probe, and a launch that cannot start workspace chat reports it unavailable rather than selecting another chat runtime. Executable, storage and other startup failures remain distinct. Listing model connections does not start the default provider. Explicit selection still validates the configured binding and the current frame/workspace before activation; it does not authorize a funding fallback or infer permission to use a different credential. Renderer recovery preserves the selected profile's history boundary. Development worker/helper resources live outside Forge's build-cleanup directory and retain the same fixed-path and binary validation.
Files bound by this id. Run grep -rn GRIDA-SEC-004 . to enumerate.
-
The native activity-order owner retains only public fact identities and bounded per-turn presentation coordinates under the existing private store owner. Its files do not contain text, tool arguments, provider reasoning or credentials. Ordering is assigned before publication independently of subscribers; observation performs lookup only and cannot invent missing historical positions. Protected native state, scoped parent/child observation and session retirement still apply. The Main order decoder requires the negotiated contract and validates positive safe integers, incomplete markers and matching attribution. Missing evidence stays unplaced; an activity coordinate cannot authorize a tool, access another chat or change execution. Decoder tests and public DTO tests retain those bounds and compatibility rules.
-
Full access selection and capture: native permission mode, private ACP adapter, Main review owner, and helper posture protocol. These add an explicitly confirmed unconfined path without relaxing restricted execution or retained-service containment. Headless evidence lives in the permission-mode process tests.
-
The development resource preparer builds the locked Rust host and helper, strips only staged copies and verifies their executable format through the same package stager. Main selects that fixed private development location outside Forge's disposable output or packaged resources, never a PATH lookup. Actual Forge cleanup tests preserve the staged worker/helper and retain the same launch-time resource checks. Ordinary macOS/Linux launches select native chat in either channel. The supervisor never starts the historical chat runtime; unavailable native chat cannot silently enable it. Windows retains non-chat services and withholds chat until native private storage is supported. This does not establish Windows kernel containment.
-
The Desktop packaging entrypoint builds from the locked workspace or takes an explicit absolute artifact root. Native agent package staging, Forge hooks, and the package verifier bind that input to fixed architecture-checked executables in application resources outside the archive. Installer makers require a fresh package that passed this check. Build output custody stays with the packaging owner. Launch-time trust and helper identity remain enforced by the native host.
-
Native agent process owner and its fixtures start the fixed resource executable without a shell. They select the child environment, negotiate ACP on private pipes, bound frames and outstanding requests, and keep the child under ownership through EOF shutdown. Only projected error codes cross the process diagnostics boundary. Renderer authorization and chat store selection are separate from this process contract.
-
Supervised provider HTTP and the Desktop provider broker use a negotiated capability on the same private stdio connection. The broker independently checks the exact configured provider route and its allowed headers. Electron's connector rechecks the live network grant at dispatch, uses the dedicated memory-only Chromium session, and starts one POST without following redirects. Upload and pull are bounded. Cancelling the exchange or closing the child aborts the request. This mode has no native direct-network fallback. The Gateway launch profile accepts only a scope label, the selected model, and the fixed Gateway base. It sends no credential over the pipe. The accepted execution fingerprint prevents a different Gateway account or organization scope from dispatching retained work. A new idle request can explicitly select another authorized connection.
-
Configured native provider selection resolves a registered model through the authenticated settings owner and binds its requests to the approved chat endpoint. A saved endpoint key is looked up by its own configured ID in shared native custody. The supervised provider accepts this selection only on a private broker launch and refuses reserved built-in key identities. The broker pipe carries key bytes only in the provider request header. The child rechecks captured credential custody after the broker buffers the request and before dispatch. Main also compares its captured stored value under the shared credential lock, rechecks network authority, and starts the request before releasing that lock. A failure after initiation is reported as uncertain. This checks observed values and does not detect an unobserved change away and back. Main's grant owner rotates the captured grant when the approved base changes, including a path change on the same origin. Retained launch profiles cannot use the new grant. Built-in OpenRouter and Vercel profiles require a selected catalogue model and a stored key from the supervisor's credential home. Their broker authorizes only that provider's exact Chat Completions route. These profiles permit manual subagents, ordinary Ultra reviews, and Goal-funded reviews under the same captured authority, as do other supported native provider connections. The built-in stored-key launch path is limited to shared custody on macOS and Linux. Process fixtures exercise built-in and configured keys and refusal after credential replacement. The isolated Desktop profile accepts only a saved provider identity and model choice. The workspace launcher resolves that selection through Main's settings and grant owners before starting the child. An unavailable selection leaves the workspace unopened.
-
The Desktop native chat client fixes the workspace context at startup and accepts session handles issued on that ACP connection. Controls use a host observation of the exact session, turn, and revisions. A reconnect requires a new attachment before the same scoped control can be retried. Process tests cover cross-session rejection, stale controls, and continuation after restart. The workspace Effort choice is forwarded only when the trusted native child negotiates it. Main preserves the exact choice for reviewed requests and refuses to resubmit a retained Ultra message on an incompatible connection. The renderer sees only whether review findings were collected in a summary for its exact observed turn.
-
Settings archives. The archive owner enumerates only registered, currently admitted workspace roots and mints bounded opaque catalog handles. The Desktop archive composition uses the shared workspace adapter for both ordinary retained-service and isolated native-profile launches; composition tests exercise both paths without creating a model worker. The Settings IPC adapter requires an admitted Settings main frame and rechecks it across asynchronous work. Listing and unarchiving use metadata-only native catalog operations, reuse the existing database owner, or open an existing closed store without a provider. They never attach or resume a session. The core's workspace-scope check excludes side chats and named children, while catalog revision checks prevent stale updates. Owner tests, IPC tests, and the native catalog fixture defend these restrictions. No renderer-supplied native path or SQL is accepted.
-
Model connection replacement. The private negotiated model-change handler exposes a read-only blocker observation and a terminal preparation to the owning supervisor. The host barrier fences controls and admission, inspects every stored session through bounded session pages, and refuses pending, active, retained or queued work, unresolved Goals, temporary side chats, running background commands and pending title requests. Successful preparation closes admission before the worker can be drained. A read-only observation alone never authorizes replacement. Main prepares the destination first, serializes workspace changes and preserves the prior selection until launch and persistence succeed. A launch failure restores the prior route with fresh handles; deferred restoration is fenced against workspace closure and later selections. Unsupported binaries refuse before replacement. No credential, provider-private replay state or execution grant crosses to the renderer. The workspace owner tests verify blocker/no-retirement, rollback, concurrent changes and closure; native process tests verify captured-route recovery and the terminal barrier.
-
Chat attachments by reference. A file attached to a native chat message that is not sent directly (any file other than a PNG or a file of up to 256 KiB, such as a video) goes by reference: the agent receives its path, name, type and size, never its bytes, and the reference grants nothing. A dropped folder uses the same reference contract with type
inode/directoryand no content byte size or media preview. Attaching it does not enumerate, copy or archive its contents and does not add a read root or grant. The renderer offers folders only when the native binary exposes the optional directory-reference bridge capability; an older binary leaves the draft intact. The renderer passes only the person's dropped, pasted or pickedFile; the preload request owner resolves its path withwebUtils.getPathForFileand refuses a page-built File or a page-supplied path, so the path never crosses into the renderer. Main resolves it again to a canonical regular file or directory, derives its type and reads only its metadata. It refuses special files and any overlap with Grida's protected stores (the chat state directory, the Desktop profile and~/.grida), including ancestor folders and aliases, before sending one ACPresource_link. The host records the reference only for a client that negotiatedco.grida/session/file-reference, checks that a workspace path names the same resource inside the chat's working directory, and never opens it. The agent reaches the resource only through its existing permissions: file tools inside the project, sandboxed commands elsewhere except protected paths. Nothing is copied, so no new readable location exists. A fork, side chat or compaction keeps the reference's description (name, type, size and path), never file content. Process tests show a workspace file read or folder listed by the existing tools and outside/protected references refused by them; Main tests cover protected folders, ancestors and aliases, special files and metadata-only resolution. -
Recorded input image previews. Main maps only validated retained image links from the attached chat to bounded opaque selectors through the input image selector. The renderer cannot choose a path, asset object, foreign message or another chat's URI. The negotiated native reader and retained image owner verify the exact locally recorded user message and session-owned asset, its digest and current visibility. Legacy PNG reads retain their old bound. Raster-original reads use at most 256 KiB per correlated chunk, totaling at most 20 MiB. Main validates media type, offsets, size and selector identity, limits reads per frame and rechecks the frame afterward. The operation is observational under a text-only model too: no inference, filesystem grant or route change. Missing or retired data remains unavailable. Video posters retain their separate display-only contract. Selector tests, worker fixtures, IPC fixtures and raster process cases exercise identity, bounds, old hosts and revocation.
-
Saved chat selections. The Main coordinator and tests own bounded non-secret draft/default records beneath the protected Desktop data root. Typed frame-scoped IPC resolves a configured connection; no renderer-selected endpoint, credential or generic file write enters the record. Main validates opened file owner, private modes, link count, size, inode and UTF-8; detects stale file replacement; and fsyncs staged data before rename and directory synchronization. Durable intents precede native changes, and finalized defaults precede cleanup acknowledgment. Unknown outcomes retain the operation identity. The native selection owner keeps independent revisions and bounded outstanding receipts under the existing exclusive database owner, without adding schema or driver-state meanings. Its private extension requires negotiation and canonical workspace ownership, excludes side/child sessions and performs no inference. Admission checks exact selected model, revision and effort; accepted retries first observe their original capture. Retirement, fork inheritance and promotion cannot resurrect retired session identities. Native process cases cover negotiation, providerless access, sole ownership and admission.
-
Explicit raster source custody. The selected-image request gate, Main source owner, native image owner and bounded preparation distinguish disk provenance, protected clipboard snapshots, retained originals and prepared model pixels. Main binds the real File or managed snapshot to session/input identity; native rechecks bounded source bytes and digest. Snapshot claims ingest only the exact protected custody subtree, never an arbitrary secret path. Disk ingestion preserves protected-root and alias refusal and grants no parent-directory or command access. Unsupported image input accepts neither text nor pixels. New model media resolves immutable retained derivatives, never a UI poster or a changed live path. Generation reference transfer retains its separate small, unchanged-PNG confirmation rules. Main custody cases, delivery cases and native raster cases verify these boundaries with synthetic providers. Request-gate cases and bridge DTO cases pin the typed input boundary before source custody is entered.
-
Desktop workspace ownership shares one startup across requests for the same registered workspace and canonical root. It bounds concurrent engine ownership and withdraws lookup when shutdown begins. It drains pending launches and closes each native child before releasing that child's provider connection. Window navigation and observer teardown do not close the workspace engine. A disconnected child stops serving attachments. The workspace can be reopened after the process owner observes exit. Reopening does not replay interrupted provider work, and the old provider connection is released before launch. A failed launch closes provider egress and retains workspace ownership if the exact child's termination is unverified. The child and its pipes must close before a replacement can start. Quarantine fixtures verify late close, refusal of duplicate launch, and unverified drain.
-
Native Desktop composition looks up the selected workspace in the retained sidecar registry before launch. It binds the main-owned Gateway connection and scoped read profile, withdraws workspace ownership on account sign-out, and drains it on app quit. Forget fences pending admissions and drains the workspace's default and saved-profile workers before the catalog removes the entry. A worker without observed exit remains unavailable to replacement. The development profile requires separate canonical browser and agent directories under an owner-only temporary root outside every known installed Desktop data and Grida home location. The ordinary workspace-only launch keeps chats in the Main-owned chat store under the browser profile. It applies the established home-secret exclusions to native workspace grants, and captures and rechecks the registered directory identity across all live or starting connection workers. Ordinary root and nested Deck requests use the same path and frame validation as catalog-backed workspaces. The retained service sandbox denies the chat store while keeping the ordinary Media owner available. Other editions can still write their own data or shared settings; this launch does not assert exclusive custody.
-
Native chat IPC is available to the current top-level workspace, verified deck, or selected SVG frame under the existing authenticated window guard. The native workspace catalog verifies the registered directory and the root deck marker or an implicit
.canvasroot. Main rechecks the deck frame and directory generation before a request and before returning its result. A root deck shares the worker for its registered directory. A nested deck requires the exact canonical bundle under the committed workspace. Its worker and saved chats bind to both directory identities, and its file grant covers only the bundle. Main rechecks the nested bundle before delivery and drains its worker on replacement, after the last frame leaves, or on parent Forget. A standalone SVG requires the exact native document owner and rechecks its physical identity before requests and delivery. Its chat worker uses private storage and a private working directory, without a project grant or external tool host. The attached editor can publish only/canvas.svgand provide a captured plain text selection. The editor still owns Save. Document window retirement drains its worker. Workbench presentation and external-agent commands remain scoped to the workbench route. Attachments and observed control revisions are issued in Main. A copied handle or workspace URL alone confers no access. Navigation invalidates the frame's attachments and observation delivery. Forget withdraws matching workspace and deck attachments and startup observations. The preload forwards bounded text and resync payloads through the typed bridge. IPC fixtures exercise frame and workspace isolation, exact control targeting, and navigation cleanup. An explicit Resume Queue for idle retained work uses the attached current observation and its revision. Reopening or inspecting the chat does not dispatch that work; older Main versions do not advertise the added action. Transcript reads use the same attachment and recheck scope after a bounded replay of committed visible text. Live updates keep their own attribution. Turn summaries take an attachment-local observation token. Main selects the latest observed settled turn and rechecks the frame and turn before returning bounded text and validated disposition counts and check statuses. Saved-chat discovery uses the main-owned workspace and a bounded cursor. Active and archived pages return bounded IDs and titles with the next cursor after the same frame and workspace recheck. Discovery creates no chat attachment. Organization derives its target from the frame's exact attachment, forwards the metadata revision, and revalidates the attachment after the native reply. The command adapter dispatches only negotiated compact and fork controls for the attached chat. Main captures the fork basis and anchor together from bounded committed history and rechecks the attachment before dispatch and after the reply. The revision adapter captures the exact observed revision and history anchor in Main. Its opaque edit token belongs to the current attachment. An unverified reply keeps both request identities and the exact replacement text and mode for retry. Desktop negotiates no configuration operation and has no settings control or send-time settings permission. A change to the workspace's agent settings file is an ordinary file write (see the agent settings file above), and Main admits a write review only for that exact file. The workspace configuration owner admits shared defaults only for a private supervising launch bound to the exact workspace state root and generation. It serializes source and active revisions through the existing writer lock. Each worker captures the active revision for new input. A pending file edit does not change accepted work. The model selector accepts only opaque IDs in the admitted workspace. Main resolves the current approved saved endpoint, built-in BYOK connection, or discovered Gateway chat model before starting a separate chat worker. OpenRouter and Vercel selections use their fixed reviewed routes and existing private key custody. Gateway choices use the default worker's captured scope without minting a grant. The separate worker verifies the opaque binding against the exact model, origin, account and organization of its own scoped grant. It uses the existing fixed Gateway chat route. Before a workspace opens, the Welcome composer can list only the workspace-independent choices (built-in provider keys and saved endpoints) through a channel IPC admission grants to the exact Welcome route, and to no native chat channel there. Main answers only the current, loaded Welcome main frame and drops a reply the frame navigated away from. The listing names no workspace, starts no worker, selects nothing and returns no saved receipt. The opened workspace commits the chosen ID through the ordinary selection above, which resolves it again. A configured endpoint profile's identity captures itsmax_tokensoutput-limit field; a saved profile reopens only when the current launch reproduces that identity under the same endpoint and custody checks. Main rejects invalid endpoint URLs and plain HTTP outside loopback before looking up a key or requesting endpoint approval. An explicitly selected llama.cpp counting connection adds only the JSON request-count route at the same approved numeric-loopback/v1endpoint. It has a distinct saved identity and uses the original key and egress checks. The private profile record contains display labels and semantic IDs. It retains no endpoint URL or credential bytes. A changed connection cannot reopen history under a different owner. Switching models invalidates the requesting frame's previous attachments and leaves other owners intact. Native startup accepts only a start flag. Main resolves the workspace from the admitted route and rechecks that scope before returning readiness. Navigation invalidates an outstanding reply. A failed native startup reports unavailability and cannot select another chat engine. -
Live editor observations require the negotiated private Desktop stdio capability. Main issues the binding for an exact authorized chat attachment. Each observation revalidates the current frame and chat. Navigation or replacement revokes the binding. Rust retains it with the accepted input, checks the reply's chat and endpoint identity, and bounds the projected workspace-relative paths. The read supplies editor context only and confers no file, network, or document-edit authority.
-
The separately negotiated SVG text tools capture one exact workbench, standalone SVG, or slide selection for an immediate Act text input. Main dispatches to the admitted frame and validates the bounded correlated response. A deck may publish one bundle-relative slide and must reply for the same observed slide. Main rechecks the deck's directory generation before sending the call and accepting its reply. The renderer owner requires the captured editor, view, selection, and revision before the existing SVG text command can run. Its result is a live edit. The normal editor save remains a separate operation. An unverified mutation reply stays uncertain and is never replayed.
-
Live presentation requires a separately negotiated capability and a subscription from the exact attached workbench. Main dispatches a bounded workspace-relative path to the authorized frame. Its receipt identifies the chat, endpoint, and call. The editor validates the target and the original view before activation. A repeated call can recover its receipt without a second send. An unconfirmed dispatch stays in the turn's evidence. The master permits continuation only for the exact trusted presentation definition and turn grant.
-
The native text observer projects assistant text from owned turns on negotiated private stdio. It checks attachment before serialization and uses the existing bounded ACP delivery window. Losing the observer or falling behind cannot cancel a turn.
-
Background attention uses a separate capability on the same private connection. The observer projects only the attached chat, turn, and verified settlement or approval wait. The Desktop worker owner fences delivery and notification clicks by the current account, worker, chat and its model connection. Main supplies fixed copy and routes clicks to the authorized workspace. An existing workbench can take only its latest pending click from the exact current main frame after it connects. Main rechecks the account, source worker, and workspace at take and discards pending targets on scope change or renderer teardown. The earlier push still supports older renderers. A reopened workspace carries the saved model selector in its local URL fragment. Selecting any target still requires ordinary workspace and saved-connection admission. Attention events are transient and grant no execution, transcript, or filesystem access.
-
Native session listing uses an explicit canonical workspace on the initialized ACP connection. The SQLite catalog queries that scope before pagination. Responses project IDs, the selected workspace and optional bounded user-entered titles. A cursor carries no global order and must anchor a session in the same scope. Listing creates no attachment or execution authority. Catalog changes require a negotiated capability, an attached chat, and the observed metadata revision. They leave execution, transcripts, and artifacts untouched.
-
Saved-chat deletion requires negotiated private stdio and an attached chat at both observed revisions. An exact scope-bound retry can recover the retirement receipt. A separate negotiated preview captures the exact owned child membership and revisions. The host fences the reviewed family under the admission owner, verifies every child belongs to that parent and workspace, and rejects outstanding work. SQLite retires the family in one transaction. Chat-owned retained attachments and working copies are removed from the exact verified private directory. Its identity commits with retirement so recovery never selects a replacement at the same path. Removal verifies the known directory layout and uses pinned descriptors. Unverified removal retains the pending record. The connection fences transcript replay, live notification delivery, and side chat creation before revoking the deleted attachment. The transaction retires SQLite records and their execution identity. Authored files, and independently retained chats have separate custody. Desktop selects the chat through its exact frame attachment, checks the observed execution and catalog revisions, and requests Main-owned native confirmation. A lost reply reuses the confirmed request. A matching receipt revokes every attachment for that exact chat owner, including subscriptions and any in-flight load that could reinstall the retired attachment.
-
Native goal controls require version negotiation and session attachment on the existing ACP perimeter. The goal owner conditions each automatic claim on the captured goal revision, allowance and original settings. It revalidates current authority before dispatch. A generated turn receives no new access; a settings file write asks like any other. For a manual goal, an explicit idle Resume records authority for one further work turn. The existing claim atomically consumes that authority under the captured goal revision and allowance; replaying the control cannot create another turn. While it is queued, a distinct Resume is refused and the pending state is disclosed only to clients that negotiated it. Pause, objective changes and Clear invalidate it. The Desktop goal adapter retains the exact goal, driver, and session revisions behind a frame-scoped token. Goal inspection is read-only. Desktop starts work through explicit user acceptance of the objective and allowance. Desktop neither negotiates nor offers check-ins. Revising the objective or criteria uses the same attached observation and request identity. The worker cancels any affected owned turn and retains its recorded work and allowance. Completion confirmation requires a negotiated, attached user control. The inspected work turn and objective revision are retained behind the same scoped token. The owner commits the exact confirmation only while idle with a settled, accounted proposal and preserves its original turn receipt. A queued goal retains its start request across restart. The Host refuses generic replacement while the goal is queued. Withdrawal uses the original input identity and the observed queue revision.
-
The Desktop approval coordinator derives a read profile from main-owned workspace selection. An approval answer takes a review issued by the coordinator for the exact session, turn, wait, and revisions. The process owner's generic RPC methods refuse raw approval answers. The typed answer uses private stdio. The fixtures exercise a real native read and retry its receipt after a child restart. The workspace pane receives a bounded display target and an attachment-local review token. Its reply supplies only the token and a decision. Main retains the action and revision basis, and navigation invalidates its tokens.
-
Native chat question tokens are issued separately from approval tokens. Main retains the exact wait and session, control, and history revisions. An answer cannot grant access. An ordinary queued message cannot answer a question. The native process fixture covers an answer during independent work, a separate queue, and stale replies.
-
Native queue edits use the attached frame's observed session revision and retained input identities. Main bounds text previews and computes a move's full ordering. It rechecks the frame after replacement preflight. Steering uses a separate request with the observed turn, control, and history basis. The queue process fixture verifies exact retries, stale revisions, and the queue held after Stop.
-
The Desktop side-chat adapter opens side chats for an attached parent on the private child connection and records which session is a side chat of which parent. Each side session is an ordinary attachment only of the frame that opened it: the native chat owner adds it to that frame's attachments, within the frame's attachment bound, so every chat method, delivery and process control takes it under the same exact-frame checks, and another frame cannot name it. Loading a side session by its ID is refused, notifications never name one, and a side chat opens no side chat. Closing or detaching one removes only that side chat; detaching its parent, deleting the parent, navigating, or a scope change removes every side chat of that parent. Each removal drops the attachment and its subscriptions before the child discards the session. Main keeps a side session it can name, including one learned by repeating a lost open by its request ID, refused for loading until the child confirms its discard, and retries an unconfirmed discard until then. A side chat's generated title reaches the frame only inside that side chat's own snapshot, validated like a catalog title.
-
The Desktop background process adapter lists and stops a chat's kept processes only when the native child advertises the capability. Main names the frame's attached chat and checks each reply against that exact session. Listings, process IDs and command text are bounded, and a stop reply cannot name a process it did not request. Listing grants no input, output or execution authority.
-
Native capability host and its fixtures bind a tool lease to a single capability and endpoint lifetime. The dispatcher checks the definition revision, validates arguments before dispatch and correlates the result with the original call. Closing the endpoint revokes its grants. A missing or mismatched reply retains the original call binding and an uncertain outcome. The executor still owns authorization at its boundary, including Electron sender validation when it routes to an editor.
-
The MCP listener and its process fixtures bind a separate, explicitly enabled local service to a numeric loopback address. It checks the exact authority and path, rejects browser origins, and authenticates each request before the SDK can route it. It shares one loopback bearer perimeter with the shared ACP listener, so both apply the same checks. The bearer value is removed before dispatch. The headless and live profiles each expose one reviewed capability independently of chat, provider, and workspace storage. Main's live export owner captures a separate private bearer and the exact selected workspace. Only its first current, authenticated workbench frame can publish bounded workspace-relative paths. Navigation, destruction, sign-out, or identity change withdraws the view without retargeting. The private pipe correlates each read and retires on framing, timeout, or connection failure.
-
The outbound MCP client captures only a trusted source's explicitly selected tools. Its HTTP transport sends the sensitive bearer only to the configured numeric loopback address and path. It bypasses proxies, refuses redirects, and bounds discovery and responses. The caller owns trust in the local peer and grants the captured lease before model use. Server annotations cannot grant access or authorize replay. Loss of a correlated result leaves the call uncertain. The native launch selects the peer and a separate environment credential before admitting work. When an Act turn also has a live editor attachment, the host binds each source independently. Tool admission routes by the exact captured grant selection, and the inventory rejects duplicate tool identities before exposing the tools to the model. Desktop Main enables this path only in an explicit disposable Gateway launch. It pins the selected canonical workspace identity and the first exact account, organization and origin scope. Main reads a bounded owner-only bearer from the protected browser profile by descriptor, refuses replacement, and passes it only in the selected native child's environment. Renderer, sidecar and command custody remain separate. Other supervised profiles fail before discovery. Turn authority binds the selected definitions to the accepted lease and excludes Plan. The opt-in native headless operation uses the same definition and execution as the standalone MCP host. It reports unavailable presentation and carries no filesystem or editor authority. A replacement MCP connection cannot resume retained tool authority. Shutdown closes the tool owners before draining owned turns. The transport fixtures and launch fixtures exercise the native server and an independent peer.
-
Private subagent controls require an attached parent and a trusted opt-in launch. The host rechecks the child's retained parent link and verified provider scope before new delivery. Discovery reads only the attached parent's bounded catalog and validates each retained parent link before returning names and IDs. Inspection binds the selected input and result to the same observed child turn. Work assignments also require the exact settled sponsoring turn. Informational messages retain their own receipts and wait for an approved assignment to claim them as attributed user data. Message delivery and exact receipt retry leave execution unchanged. Pause, Resume, Steer, and Stop target an exact child turn and use the ordinary revision checks. Stop atomically holds the child queue. Resume, queue release and Steer revalidate provider continuity. Child creation holds the session admission lock through the parent check and durable insertion. The allocation policy binds a work reservation to the ordinary durable claim. Manually created named assignments receive no workspace, tool, or delegation grants. The process fixtures check attachment scope, restart, exact result attribution, and allowance reuse.
-
General delegation is a separate operation-owned worker profile, not a widening of manual children or reviewers. New ordinary Act intake captures its exact product policy and bounded allowance. Each spawn operation admits one child under its original provider and permission capture; replay reconciles that child instead of repeating admission. Native tools and skills are explicitly rebound to the child; live editor handles, settings writes, extra approval and recursive delegation are unavailable. Ask remains a refusal in the worker, never an automatic grant. Worker-owned process capability ends with the assignment. A required private completion check records retirement before success; fallback and explicit Stop also request cleanup. Collection is observational and cannot manufacture verification from an empty process table after restart. Task status and resource retirement are distinct receipts. Parent controls fence admission and propagate to owned children, preserving independent pause. Worker authority tests and built-process cases cover captured authority, neutral artifact work and read-only/Ask boundaries. The master policy accepts completion evidence only from its exact captured tools and live grants, correlated by child, accepted input and execution turn.
-
A sponsored child profile binds one funded slot to an exact source turn and tool operation. Starting that child checks the admitted operation's definition, arguments, grant, and attempt. The claim transaction verifies current source ownership and controls before admitting a worker. The child uses the captured model and operating regime with a separate text assignment and does not automatically inherit the parent transcript. A new anonymous ordinary review may receive a child-bound read-only grant for the already-allowed primary directory. It receives no additional-directory grant, commands, writes, approvals, or delegation. Existing protected-path rules still apply within the primary tree. Goal-funded, named, and older text-only work retain their original scope. The host verifies the retained parent, profile and directory identity again on recovery. Exact start retries observe the retained assignment without redispatch. Parent Pause and Stop, including cancellation and shutdown, apply through the operation pair transaction, which verifies the exact child claim or fences the absent slot. The child's product state distinguishes independent and ancestor pause causes. The native host returns the committed receipt on exact retries without advancing either control. Parent Resume commits the related disposition with the parent lease. An independent child Pause remains in force. A reopened child reclaims its own lease from the related receipt's exact binding and driver revision. Current launch and provider authority are checked before dispatch. A later paired Pause or Stop fences an earlier wake. Replaying a committed Resume can recover readiness after a lost response or process restart.
-
A named Goal reviewer is an existing child of the attached parent and shares its funded review slot. Goal admission checks ownership and captured provider authority. The named assignment owner binds the Goal revision, parent turn, child input and exact child turn. The existing claim transaction consumes the slot and the child's allocation together. Paired controls and late accounting follow that assignment, with ordinary child work retaining separate accounting.
-
Ultra captures the separate parent and child allowances with the accepted input. Only that turn receives the exact review start and collection grants. The start uses the active parent attempt and current controls. Recovery can observe the originally admitted child without launching another. The collection tool verifies the parent operation, accepted child input and exact child turn. It returns a bounded excerpt of verified findings, or a disposition without findings, and leaves child execution unchanged. Private ACP accepts an explicit effort only when the trusted launch supports sponsorship and the client negotiated the capability. Changed effort cannot reuse an accepted input or revision request. Queue edits retain accepted effort and steering keeps the current turn's choice. Reviewer admission depends on the harness and JSON-tool capability, not the provider's identity or an optional wire output-token field. Parent and child use the same captured execution and transport. Generation steps, deadlines and output-byte limits remain bounded; an omitted provider token cap does not promise a remote token or quota ceiling. Real monetary reservations and Gateway child receipts retain their separate existing enforcement.
-
Native Desktop opts into named children through a trusted launch with the captured provider transport, independently of its provider protocol or funding. Main derives the sponsor from the exact attached parent observation and retains that sponsor for an exact assignment retry. It checks child, input, and turn identities before returning bounded assignment and result text. A frame receives a control token only for the displayed assignment's current turn. Main keeps the child identity and the session, control, history, and execution revisions behind the token. Pause, Resume, Steer, and Stop revalidate the exact attachment before dispatch and after settlement. An exact retry uses the original request identity and basis. Informational messages and queue controls use a separate bounded child-observation token. Queue mutations use the captured revision and selected input identity. The message result echoes the retained input and text without dispatching an assignment. Launch, Main adapter, IPC, bridge projection.
-
Rich child observation uses its own negotiated private capability. The native projection and private protocol require an attached parent, verify each child's actual parent and hold the parent's retirement barrier during reads. Ordinary session loading continues to refuse child sessions. Status pages, retained lifecycle events and visible conversation pages are bounded; provider reasoning, continuation state and credentials are excluded. Actual uncommitted visible text has a bounded transient cache and reports missing or shortened progress explicitly. The Main observation adapter validates returned parent/child identity, count/event/message limits and public fields before projection. Older-page continuations are replaced by bounded attachment-local tokens bound to the exact parent session object and child. A token from another window, attachment or child grants no read. IPC admission revalidates the current frame and attachment after asynchronous reads; the native adapter rechecks its own parent attachment and negotiated availability too. These operations expose no ordinary child attachment or control token and start no inference, recovery or tool work. Existing child controls keep their separate observed authority. Projection and cursor tests, Main/native execution tests and public bridge contract tests retain these separate boundaries.
-
The native-chat invoke adapter preserves canonical machine error identity across Electron's invoke envelope. It accepts only the exact envelope for the invoked known native-chat channel and a whole bounded ASCII machine code. It never recognizes a substring in arbitrary prose, a nested error or an envelope naming a different channel. A recognized code crosses as a fresh error without the original stack, cause or diagnostic fields; unknown rejections retain their existing meaning. This adaptation grants no dispatch or retry authority: the client still requires its exact authoritative absence code before retrying an unchanged input identity. Unit tests and the sandboxed Electron regression with its isolated fixture cover that transport boundary. The native draft-promotion regression exercises durable chat and first-input identity independently of this error transport adaptation. Preload still exposes the original typed bridge object under its existing path guard; optional methods and subscription ownership are unchanged.
-
Portable Rust provider contracts: crates/grida-ai/src/catalogue.rs, crates/grida-ai/src/discovery.rs, crates/grida-ai/src/input.rs, crates/grida-ai/src/lib.rs, crates/grida-ai/src/media.rs, crates/grida-ai/src/sse.rs, crates/grida-ai/src/tripo.rs. These preserve this boundary. Rust conformance adapters, where present, are feature-gated and excluded from the distributed executable.
Direct Tripo model generation adds the SDK client, validated inputs, and client tests, plus the host route, wire contract, route tests, and daemon integration tests. Only the fixed Tripo API origin receives its key; enumerated Tripo asset hosts use the credential-free download lane. The feature accepts bounded inline images, never caller-selected URLs, and persists downloaded GLB bytes rather than expiring provider URLs. Existing auth, Referer, preload and native transport controls apply to the new route.
The shared SDK rigging boundary additionally binds rigging-client.ts, rigging-inputs.ts, rigging-operations.ts, producer tests, and tripo-transport.ts, the internal upload/task/GLB validation transport shared with model generation.
Mesh rigging keeps structured eligibility separate from media output through
rigging routes,
wire contracts,
route tests, and
daemon integration tests.
The existing three_d capability admits both operations in the media
composition. One operation holds the upload/decode memory reservation
until its result is encoded and saved. No input path or URL grants filesystem or
network access; source GLB bytes are uploaded without mutating saved media.
Native caps.media.rigging and both optional bridge methods gate older builds.
Authorized multipart POSTs to the exact Tripo /v3/files endpoint receive
a 64 MiB native request allowance (covering the SDK's 60,000,000-byte mesh plus
multipart framing). The separate provider:tripo-upload grant admits only
HTTPS PUT to tripo-data.s3.us-west-2.amazonaws.com, with an
application/octet-stream body of at most 60,000,000 bytes. No Authorization,
cookie or API-key header is permitted, and main refuses every upload redirect.
Other requests keep their 32 MiB cap. Electron main's
64 MiB aggregate upload budget, per-frame bounds and credential-free result
download grants remain enforced.
Funded Tripo uses the same feature routes with explicit provider: "gg" and the
composition's existing in-memory GG store, never a BYOK fallback. The SDK owns
the bounded native inputs (20,000,000 bytes per image, 60,000,000 bytes per mesh),
reference preparation, fixed signed PUT and 64 MiB self-contained GLB output.
The hosted server admits already-uploaded file tokens only after verifying its
owner-bound ticket; renderer/native input remains bytes, not provider tokens or
URLs. The direct SDK's separate uploaded-input methods validate exact token/media
type shapes and are unavailable on the GG lane.
caps.media.tripo_gg and caps.media.rigging_gg distinguish funded-capable builds
from earlier BYOK-capable builds. Bridge dispatch refuses unsupported funding
without switching providers. These additions bind the
GG SDK adapter,
adapter tests,
uploaded-input and receipt tests,
native funding tests,
bridge contract and
contract tests, plus the
preload and preload tests.
The network policy,
sidecar transport,
main network host and their respective
policy,
sidecar, and
main tests pin the separate upload grant.
-
Windows credential compatibility tests and provider composition tests — platform-selected host-local custody, preserved OAuth records and keyless GG image resolution, with strict provider failures that never switch the payer to GG. These simulate platform selection with disposable files; they do not certify native Windows ACLs.
-
Public SDK exports, operation discovery, shared route eligibility, input rules, and schema primitives — credential-free descriptors and JSON parsing share execution's route and input policy. Discovery neither constructs authority nor promises access. Image count is bounded before key reads or paid submission. Public discovery tests and native parser parity tests pin those boundaries.
Today:
- Media server entry, shared host composition, media server tests, and built-entry isolation tests — the media composition mounts existing routes behind the daemon perimeter and receives the same narrow credential, provider-HTTP and media-persistence capabilities. It adds no query-string credential, native-provider route or command executor; endpoint-provider routes mount only when the host opts in. It is the only daemon tenant.
- Media tenant wiring tests — every generation route group receives the same host media service; music receives no BYOK store and the ElevenLabs groups receive no GG authority.
- Desktop composition and its tests — select retained services before loading the server; their option types admit only disabled or native-chat service modes. Native OAuth lives in its dedicated host; no command executor is supplied to the retained service. The supervisor tests pin disabled-mode argv and the absence of scratch preparation while retaining the outer network fence.
- An admitted native preview excludes known Grida homes and installed Desktop data from workspace and standalone document admission and the retained sidecar's read and write scope. The file registry rechecks those exclusions for retained document IDs and refuses hard-linked files in this profile. The exclusions use known launch paths.
- An ordinary macOS launch with the agent disabled can register selected SVGs through Main's file owner. The exact file and its parent identity constrain the native read and save worker. Known agent roots, Desktop stores, the media root and packaged resources stay excluded. The file-only preload argument grants neither a native chat binding nor durable chat identity.
- The ordinary native-chat launch uses that same selected SVG owner with private Main-owned document identity receipts. A selected document frame can attach only its exact rootless chat and captured text selection; it receives no surrounding-directory or general filesystem authority. Disabled-agent startup retains its file-only behavior.
- The native chat store takes its path facts from the primary app's sidecar supervisor, which fixes them before any retained service starts. Its retained sidecar composition provides media and configured endpoint settings without a chat or command tenant. The store lives under the browser profile apart from the agent data, provider home and media root. Its one ownership record binds those path facts; it refuses state it did not record, a record with other fields, or a store recorded for other profile paths. Each workspace store binds the selected workspace identity and canonical root in a private directory. Fixtures exercise refused state, credential overlap and workspace isolation with real native processes.
- The native Plan regime selects investigation tools under the existing read grants and keeps command, working-copy mutation, settings changes and timer tools out of the turn inventory. The durable input captures the regime. Queue edits and restart cannot widen Plan to Act. A Plan launch can observe or stop retained Act work and refuses to resume it. Process tests cover captured authority through queue edit, restart and separate Act submission.
- The native turn summary requires a negotiated capability and an attached chat. It reads the exact settled turn and projects bounded plain text, tool disposition counts, unresolved counts, check statuses, whether independent review findings were collected, and provider-reported token subtotals in a fixed set of categories. Raw operations, arguments, child identities, provider state, and attempt-level usage attribution stay in the host.
- Native goal host binds goal tools to the exact session, reserved turn, and goal revision. The tools read captured goal metadata or record a proposal. Their grant cannot authorize workspace, command, or provider operations. Explicit goal acceptance retains the selected permissions and uses the ordinary queue and turn owner.
- An Ultra Goal draws its review share from the existing Goal reservation. Funding observation verifies the same parent operation and child input as review collection, then reads recorded attempts from the exact child turn. The Goal host retains unresolved allowance and reconciles definite late work against the current driver-state revision. While a funded turn owns work, the client uses the paired task controls for Pause, Resume and Stop. Process fixtures verify allowance, held usage, restart and control behavior.
- On supported native connections whose worker negotiates review, Desktop can offer an Ultra Goal and explicitly reconcile a held review through the attached Goal inspection. The negotiated native control binds the exact objective basis, revisions and reserved turn to an account-only receipt. A stale inspection or unverified outcome cannot release held steps.
- The optional Goal file verifier matches each configured criterion to its complete native read under the exact recorded turn grant. The launch profile bounds and binds the rules to the captured authority. The Master gives the model bounded references to verified operations and independently checks the cited evidence at settlement. Built fixtures cover mismatched criteria, paths and bytes, and retained observations after restart.
- The native wake-up ACP extension requires private stdio, a negotiated capability, and an attached session. The timer host binds an explicit opt-in to its admitted turn, resolves the exact wait, and uses ordinary continuation authority. Restart recovery requires a separate identified request. Process tests cover private scope, ownership, cancellation, and restart.
- Private Goal Start can opt into one check-in for its first Standard Act reservation. The Goal host binds the opt-in to the accepted input. Goal Resume signals the timer after its durable control commits. Cancellation still requires exact explicit continuation. Automatic Goal follow-ups use the remaining allowance and receive no timer grant from the original input.
- Native completion checks
require trusted launch selection and an exact turn-bound grant. The built-in
text check uses only the bounded recorded answer. An optional command in the
launch profile runs in Act under
the existing read-only primary scope and no-network command supervisor.
It receives literal arguments and bounded event input without inherited
credentials. Native preparation
verifies the reviewed digest against the bound executable identity. The
executable custody check
requires an unprivileged launch and proves the canonical system executable
and its ancestors are root-owned, without non-owner write access or extended
ACLs. A separate unprivileged profile cannot use its write grant to modify
these bytes. Both checks stay outside the model's tool inventory. A trusted
hook-only profile also withholds the general command offer and its grant.
The private check retains the same sandbox and cleanup owner. A trusted
beforeToolprofile can also require the private pre-tool check for an Act command after permission and before the target attempt. It receives the bounded validated command arguments: the command line, working directory, terminal choice and access. Later process input is not checked. The check cannot grant the target authority. An unconfirmed check blocks later admissions in the same turn after it is observed; effects already admitted can finish. This profile supports Standard Act Goals; Plan and Ultra Goals remain unavailable. Process tests cover hook-only launch, refusal of a matching user-owned program, launch changes, interruption, and exact retained attempts. - Private side-chat controls
are offered only on private stdio, require negotiation and an attached
parent, and attach the side chat only to the opening connection; another
connection cannot load it. The side-chat owner
forks the parent's committed history through the ordinary
fork lowering, which
excludes source system instructions, tool payloads, reasoning and provider
continuation state. A side chat is an ordinary session under the parent's
execution, workspace and captured permission profile, so it gains no
authority the parent lacks; approval
askrules still ask. Its writes and commands are not structurally blocked: the side-chat policy and history boundary steer the model away from mutation unless the person asks, and only the permission profile bounds what a tool may do. The host refuses delegation, subagents, goals, wake-ups, forks, nested side chats, manual compaction and catalog changes for a side session where each is admitted; automatic compaction may summarize only the inherited history, before the first side turn, and the boundary follows that summary. The host rejects a retained side input that carries any refused option. The inherited history is model context only: replay, transcript windows, history pages and revision targets of a side session begin after it, and leave out the summary of a compacted copy, so a side chat never re-presents the parent's conversation. A parent holds at most eight open side chats and a connection thirty-two. Side sessions live in a catalog scope outside every workspace, and a side chat's generated title stays on that session's own record, readable only through its snapshot on the opening connection. Close, parent deletion, connection shutdown and the sweep a host runs before serving cancel their work, stop their processes and discard their records, spending authority and retained attachments; unconfirmed cleanup leaves the session fenced for the next sweep. Process tests verify private scope, parent permissions and approvals, refusals, the transcript beginning at the boundary, the per-parent and per-connection bounds, a title kept out of the catalog, and every discard path. - The chat title owner titles an untitled chat from its first request through a temporary host: a separate in-memory journal, only the selected inference authority, and tools denied. It writes the title only while the chat is still untitled at the same catalogue revision, as the chat's own record rather than a person's catalog action, so it also titles a side chat that refuses those actions. A client opts in at launch. The process test verifies a tool-free title request and that a rename is never replaced.
- Desktop media startup proof, build fixture, and runtime guard — actual Vite sidecar output, private framed provider/control traffic and main-transferred loopback sockets, with synthetic BYOK/GG responses and owned temporary state. Import/network tripwires and absent chat/scratch files test startup isolation; they are not an OS-sandbox, installed-app or provider integration certification.
- The isolated native Desktop profile gives Main sole ownership of
recent.jsonin its private browser directory. Its recents IPC uses the current authenticated top-level frame. Paths are remembered metadata and document admission remains separate. The retained sidecar withholds its recents routes and denies file contents and mutation under the browser directory. Compatibility launches retain the daemon store. Native startup leaves the legacy store in its original location. - The isolated native Desktop profile registers workspaces through the Main catalog. The current native folder picker or a Main-owned OS open admits a new directory. Reopening from the renderer must match a registered canonical path and directory identity. The catalog lives outside Chromium state under the instance-locked profile. Its bounded reader validates each committed scope and the directory identity. The confined compatibility carrier mounts only its guarded file routes for that catalog, and the sandbox denies writes to the catalog directory. Native chat startup resolves the Main catalog, and the packaged range reader opens the exact admitted directory. Existing profiles retain their compatibility registry.
- The native workspace span reader binds metadata and output to one descriptor. Its private process requires the registered directory identity and protected roots before opening a file. Bounded chunks recheck the open inode and current grant before exposing bytes. Process tests verify exact byte spans, refused paths and read-only Seatbelt composition. The buffered editor reader uses the same worker on the qualified packaged native profile. It reads only from the catalog's current directory identity, revalidates before returning bytes to the attached frame and preserves the descriptor's fractional modification time for the existing write precondition. The directory reader enumerates one pinned directory without following child symlinks. It verifies the directory again before returning the complete bounded listing. Desktop uses the same catalog and frame checks as buffered reads. The workspace writer runs with a separate kernel scope and pins the destination parent. It checks the existing target and any supplied fractional modification time before atomic replacement. Main holds catalog mutation until the admitted save settles and retains ownership if process exit cannot be confirmed. The read worker retains its read-only profile.
- The selected document worker checks protected paths and the exact canonical file and parent identities. Its Seatbelt owner grants parent metadata and one readable file. A save can write only the selected name and its one private staging name. The read scope cannot list the parent or read sibling content. Built fixtures cover a direct child of a synthetic home, aliases and replacement, stale saves, and streaming above the separate workspace text limit. The packaged macOS arm64 native profile registers trusted standalone opens in the Main file owner. The IPC handlers require the exact assigned window, top-level document route and document ID. Navigation revokes the active request and invalidates the read basis for saving. Closing a window does not release a dispatched save before its child exits. Owner fixtures cover retirement and uncertain writes. The preload advertises its local file capability only at the route with the ID assigned to that window by Main. The private document identity store verifies a bounded receipt for the selected path digest and exact file and parent identities. Main advances the key after a verified save and checks the live file and window owner before returning it. An unverified replacement cannot inherit the previous key. File access stays with the exact document worker.
- The native Open Recent menu and recent projects palette reopen a saved project through the existing catalog before navigating. After authenticated entry admission, native file and catalog opens can proceed while the retained sidecar restarts. Other opens still require a live sidecar, and initial entry still waits for retained readiness. A replaced folder requires a fresh native picker selection. Menu and Range fixtures check refusal and the exact grant after restart.
- Host media error mapping — callers supply safely projected SDK failures before logging/status adaptation. The mapper logs supplied details and must never receive raw upstream errors; provider details are removed by each operation and route boundary.
- Shared 3D operations and endpoint tests, and lifecycle tests — three explicit fal model contracts with private input/key snapshots and safe byte-only results. Authenticated queue URLs must use exact
queue.fal.run; primary GLB downloads use the existing fal asset namespaces without credentials. The shared media invocation bounds the ten-minute generation, including key lookup, polling and download. JSON is capped at 1 MiB and GLB at 64 MiB with header/version/length checks; no paid retry, provider URL, raw error or filename reaches the result. The 3D host route, its tests, wire protocol, and composed-daemon storage proof retain wire admission, bounded base64 decoding, exclusive generation, fixed filenames and optional receipts. This replaces the former agentfal-three-d.tsadapter; it grants no new provider or GG authority. - editor/lib/supabase/server.ts —
createClientFromBearer(bearer-auth shim for existing private editor routes that allow Desktop-originated calls without browser cookies). - Shared provider credential admission and its tests — pure first-party key normalization and explicitly invoked authenticated checks. Checks require an injected provider transport, use one fixed HTTPS GET with a ten-second deadline and bounded JSON response, reject redirects, and expose only safe result/failure codes. They never store credentials or run implicitly before generation. The SDK contract records official format evidence, permission limits and the separate authority required for future custom endpoints.
- Shared image operation, provider HTTP, BYOK image adapters, GG request helpers, URL admission tests, GG image adapter, and provider entry — caller-selected provider authority, live credential reads, distinct request/download lanes, and safe image outcomes. The operation never retries a failed paid batch; requested multiple images may require multiple provider-sized batches. Existing agent imports delegate to these owners. The SDK contract defines host responsibilities. Image operation tests and download tests pin credential isolation, safe failures and bounded asset reads. The queue and URL helpers, their tests, and BYOK adapter tests preserve provider-owned polling and credential-free result downloads.
- HTTP image adapter tests — existing admission and host persistence around the shared operation, reference capability before file reads, safe host failures, and no paid retry.
- Shared video operation, provider adapters, and bounded invocation — video resolution and execution without host types. One submission uses the selected provider and a private invocation credential; a changed key cannot retarget an accepted job. The exact fal
fal-ai/veo3.1/lite/image-to-videobinding admits one HTTPS frame or PNG/JPEG/WebP bytes up to 8,000,000 bytes. Shared native/JSON rules expose that exact capability, bound base64 before decoding, snapshot bytes before credential lookup, and reject unsupported representations/options before generation authority. Its private adapter creates a bounded inline data URL and maps accepted numeric duration/dimensions to the documented fal wire. Other bindings retain HTTPS-only frame inputs; no filesystem read, upload route or new host grant is added. Submission, polling and result reads share a deadline and cancellation. Provider-owned URL restrictions and separate request/download lanes remain enforced; all result representations are bounded before bytes reach the host. HTTP admission, base64 wire responses and media persistence remain in the video route, with a thin resolver adapter. This replaces the former agentvideo-byok.tsowner. Operation tests pin provider wires, image input bounds/snapshots, credentials, cancellation, deadlines, hostile results and safe failures; route tests pin the host contract. - Shared music operation and its tests — GG-only text-to-music with no BYOK credential capability or direct Replicate access. Current operation metadata selects a supported JSON contract; the scoped token stays on the Grida API submission and original-job status requests. Result MP3 bytes use only the credential-free, host-authorized asset lane. The shared media invocation bounds its lifetime and response reads; only bounded MP3 bytes and MIME type leave the operation, and download failure never resubmits generation. The music route retains HTTP admission, canonical filenames and optional root-level storage receipts, pinned by route tests. This replaces the former agent
gg-media.tsmusic adapter. - Shared sound-effect operation and its tests — the existing ElevenLabs BYOK model uses one fixed provider endpoint and a live key from the host's narrow reader. No GG credential or download destination is available. The shared media invocation bounds credential lookup, response reads and cancellation; only nonempty MP3 bytes within 16 MiB and a MIME type leave the operation. The sound-effects route and its tests retain admission, missing-key status, wire encoding, filenames and optional root-level receipts. Safe failures omit credential and upstream details. This replaces the former agent
elevenlabs-sound-effects.tsadapter. - Standalone package proof, cleanup/report tests, runtime guard, image consumer, video consumer, music consumer, sound-effect consumer, speech and voice consumer, 3D consumer, and guide — packed public exports with only declared production dependencies, synthetic transports, and guarded ambient network/credential/state access. No Grida host is installed or started.
- packages/grida-daemon/src/path-contains.ts — shared
path.sep-prefix containment used by the media store's containment asserts, protected-root overlap checks, andcreateProject's managed-root assert (one source so the discipline can't drift). - packages/grida-daemon/src/media.ts and protocol/resources.ts — host-rooted durable binary-media store and its path-free DTO vocabulary. Entries use opaque UUID directories, validated single-segment filenames and MIME types, owner-only atomic writes with metadata committed last, bounded whole-file reads (64 MiB), descriptor-relative realpath containment, exact-root symlink refusal, and
O_NOFOLLOWfile handles. Save admission is serialized per store instance and refuses new items past 512 committed records or 4 GiB logical bytes; it never evicts published media. Corrupt or incomplete entries fail independently. Native path resolution exists only on the Node-only server export and is omitted from the tenant's persistence-onlyDaemonServices.mediaview; there is no media HTTP route or generic renderer filesystem capability. - packages/grida-ai-host/src/http/routes/generated-media-persistence.ts, images.ts, video.ts, three-d.ts, music.ts, sound-effects.ts, and text-to-speech.ts — generated image/video/3D/music/sound-effect/speech bytes are best-effort persisted through the optional host media service. Only a neutral filename, MIME type, and bytes enter the store: prompts, provider/model identity, credentials, and native paths do not. Text-to-speech voice discovery additionally projects upstream rows to bounded
{ voice_id, name }values. A persistence failure is reduced to a generic warning and cannot discard or replace the already-generated response. - Shared text-to-speech operation, speech tests, and voice discovery tests — exact-origin ElevenLabs BYOK speech and bounded voice discovery. Generation validates text and one encoded voice path segment before submission; listing keeps one key snapshot across bounded pages and projects only IDs/names. The existing media invocation bounds key lookup, provider requests and result reads. Nonempty MP3 output is capped at 16 MiB; no GG or download authority is available. Safe failures retain actionable provider denial without upstream bodies or credentials. The text-to-speech routes and their tests retain admission, wire/status adaptation and optional root-level receipts. This replaces the former agent
elevenlabs-text-to-speech.tsadapter. - packages/grida-daemon/src/workspaces.ts — opened workspace registry and root canonicalization.
- packages/grida-daemon/src/workspaces/fs.ts — guarded file operations over a containment scope (a
{ id, root }: the workspace, or the session scratch dir — NOT tied to the workspace registry). Every read/write realpath-checks containment to that scope's root, so a symlink escaping the scope is rejected regardless of which scope it is. The streamed-media export (openFile) goes through the sameresolveInsidecontainment (resolved once per request) and then pins the read to a contained file descriptor: it opens the realpath'd targetO_NOFOLLOWand fstat-streams from that handle, so a symlink swapped in after the check (the realpath→read TOCTOU) fails the open instead of escaping — the same defense as scratch writes. It is deliberately uncapped because streaming has constant memory; whole-file reads remain bounded separately at 1 MiB for source text/default byte reads and 8 MiB for the buffered workspace-resource route. This is also why the TOCTOU hardening matters more here. - packages/grida-daemon/src/http/routes/workspaces.ts —
/workspaces/*registry + fs routes, including the streamed, Range-awareGET /workspaces/filethat thegrida-workspace://scheme proxies to. Same Auth/Origin/Referer guards as the base64 readers; containment viaworkspaceFs. - Workspace media protocol, Main registration, profile selection, read worker owner and route tests — the
grida-workspace://handler selects the compatibility proxy or an exact native registered directory. The native worker receives one range over private pipes with no network or fork grant, and Main bounds children until process close. The shared Range response formats an already authorized byte reader. desktop/src/preload.ts— path-scopedcontextBridge; password fetched through guarded IPC and held in closure. Its daemon HTTP client is the chat-free media transport (handshake, files, secrets, provider endpoints, hosted-AI session and media generation); the TypeScript chat members (agent,sessions,caps.agent, directory scopes) are no longer exposed, so no renderer path reaches chat, session or directory-scope routes. The optional media namespace uses native IPC only and accepts opaque ids, returning path-free descriptors and bounded structured-clone bytes.- packages/grida-desktop-bridge/src/index.ts — renderer-safe bridge protocol and DTO vocabulary, including the optional path-free media library contract.
desktop/src/bridge/contract.ts— Desktop-local IPC channel vocabulary plus re-export of the renderer-safe bridge contract.desktop/src/window.ts— blocks exposed desktop windows from navigating outside/desktop/*; injects non-secret preload arguments.desktop/src/services-sidecar.ts— retained-service entrypoint; Main is its sole spawner, and it accepts only main-transferred daemon sockets.desktop/src/services-sidecar-daemon-sockets.ts— injects only validated, already-connected socket capabilities into the unbound HTTP server; it exposes no listen, bind, connect, or target-selection operation.desktop/src/services-sidecar-channel.ts,provider-network-policy.ts, andservices-sidecar-network.ts— strict private stdio framing, destination/header policy and the sidecar's explicit provider/provider-asset transport client. The channel carries no host command lane:command.*frames are unknown types, and malformed or unknown frames fail the channel.desktop/src/main/services-sidecar-socket-host.ts— owns the exact loopback listener, pauses accepted sockets, rejects non-loopback peers, and transfers the bounded connected capability over per-spawn Node IPC.desktop/src/main/provider-network-host.tsandprovider-network-authority.ts— main-owned Chromium network execution, bounded response streaming, redirect/route reauthorization and per-spawn built-in/custom grant state. Main executes no command for the sidecar; native model commands run in the Rust host.desktop/src/main/provider-endpoint-consent.ts— protected Main-owned durable endpoint receipts, explicit Save consent, exact binding restoration, non-minting discovery and serialized revocation. Consent cases and startup cases pin persistence and ordinary startup/restart wiring; adjacent authority, supervisor and Settings IPC cases pin transport ACK and frame admission.- The finite command supervisor runs reviewed hook and completion checks. It retains the authorized scope, owns cleanup across runtime cancellation, and reconciles the original attempt.
- Model commands run through the chat process store and its command tools. Each launch uses the approved scope and captured environment; later input reaches only that chat's own processes. Stop, eviction, deletion, scope lifetime and shutdown end them; a changed permission profile governs only later launches, and unverified cleanup is reported at shutdown. The native session and trusted helper end a session at its scope deadline, on stop or handle drop, and when its owner disappears. The private process controls list and stop processes only for an attached chat on a negotiated private connection. Command tests, process tests and native sandbox tests cover this boundary.
- The confined ACP turn driver is selected only by a trusted embedding. It requires a reviewed executable and revalidates the exact prompt grant before dispatch. The sandbox's bounded stdio carries no inherited credentials or ambient network grant. Peer callbacks cannot confer permissions, file access, or terminal access. The owned worker retains the turn lease through process cleanup. A retained handoff without a receipt cannot cause automatic replay. Native peer and SQLite fixtures exercise this boundary. The headless launcher selects an owner-private profile and pins one read-only workspace. The state, profile, and private Grida roots are outside the peer grant. It claims the turn before publishing acceptance and verifies settlement against that same SQLite store. The native fixture also exercises this built entrypoint. The installed CLI route uses that same launcher before opening account or provider authority. The explicit profile selects the reviewed system executable, scope, and helper. The Desktop external run owner accepts a private Linux launch profile, checks the registered directory identity, and pins the helper and system bubblewrap. An installed preview requires an administrator-owned copy matching the packaged helper's digest. The peer's runtime is limited to its reviewed executable and the fixed glibc loader and library roots. The package tree remains protected. Desktop records each request identity before dispatch, sends the prompt on private stdin with a cleared environment, and keeps replacement blocked until the prior owned work has a verified cleanup receipt or evidence it did not dispatch. Main subprocess fixtures cover exact retries, Stop, frame withdrawal, and recovery of missing replies. Desktop composes this owner after the primary instance admits an isolated Linux native profile. The native workspace catalog reserves dedicated peer scratch against ordinary workspace grants. It checks the exact scratch identity and keeps existing custody denials for the peer. Forget waits for the selected owner to drain before withdrawing the workspace. The optional Desktop bridge exposes status, identified text submission, and Stop. Main IPC restricts the capability to the selected authenticated workspace frame and its exact observed run. Navigation withdraws the observation and closes pending admission.
- The native permission owner resolves an explicit host profile, binds a durable decision to one action and its captured scope, and fences revocation at command spawn. Sandbox preparation checks the exact opened directory and captures executable and scope identity. Native permission tests cover decline, restart, identity changes and revocation.
- The native approval extension requires the private supervising stdio client for answers. Attached shared clients can read pending approvals. The host checks the retained action and revisions and holds the execution slot while a reviewed hook check's command cleanup is pending; unverified hook cleanup stops automatic queue advancement. Model command processes belong to their chat and do not hold the slot; deletion and host shutdown clean them up. Process tests cover private review, restart, exact retries, cancellation, and confined command dispatch.
- Trusted launch configuration can select automatic review for one exact file read already governed by
ask. The review policy bounds the evidence and gives the selected provider no tools, absolute root, or file content. Only a valid retained result on the same action, scope, control, and history basis can answer the ordinary pending approval. Manual decisions and current file grants still govern. The host filters reviewer output before the public stream. Built tests cover exact scope, manual precedence, restart, and interruption. - The native ACP confinement fixtures retarget a folder alias into a protected root during approval and verify both direct and aliased reads and writes are refused under Seatbelt or bubblewrap. The Linux cases probe socket denial inside the command namespace and verify detached work stops, retaining explicit uncertainty when native cleanup cannot be confirmed.
- Each shared ACP listener has one bearer and one trusted Host. Deploy independent authorities as separate processes with separate private state, listener tokens, provider grants and workspace profiles. The built deployment fixtures exercise cross-token and cross-session refusal, duplicate state ownership, separate provider routing, and concurrent native command scopes. Whole-host containment depends on the deployment's own filesystem and network isolation.
- The native workspace bindings and retained input store separate captured locations from current grants and enforce supplied protected roots. Working-copy receipts retain their source identity. Workspace tests and scratch tests exercise replacement, traversal, private publication and restart.
- On a profile with image-bearing tool results, workspace image inspection uses the ordinary exact read grant. The captured legacy definition retains PNG/256 KiB behavior; the new captured definition accepts bounded PNG/JPEG/WebP/GIF preparation. Both retain source/version checks and correlation between the tool result and the next provider request. Later context identifies elided pixels. Process regressions and raster cases cover source replacement, decline, aliases, retained bytes and old definition reconstruction.
- The legacy inline-PNG ACP input path and queue handlers accept image bytes only from attached private stdio clients with a supported provider profile. The image host validates the PNG and retains it outside the authored workspace. The Responses adapter and compatible adapter resolve the exact original only for admitted provider requests. The compatible profile requires a listed model whose OpenRouter binding declares PNG input, the canonical OpenRouter route, and the saved credential source. Process tests exercise queue restart, byte identity, and shared client refusal. The saved-provider fixture checks exact PNG egress and refusal on unsupported profiles using synthetic credentials and responses.
- The trusted embedded run can supply one explicit local PNG argument. The image host opens a bounded regular file without following a final symlink, checks the opened version, and validates it before input acceptance. A run with no selected project uses a private empty context identity and grants no project access. The built fixture reopens the exact crop and verifies the original file bytes and directory contents.
- The Desktop PNG picker supplies bytes from a selected browser file. Main checks the private child's advertised image capability, exact chat attachment, byte limit, and PNG signature. The bridge carries image bytes only. The Desktop process fixture exercises exact retry, queued-image preservation, and both native admission paths.
- Desktop selected-file intake carries one bounded byte buffer and a display name through the path-scoped preload and attached chat IPC. Main validates the name and bytes and rechecks the attachment after submission. The private ACP routes require negotiated selected-file intake and verify the bounded payload before staging it. This creates no filesystem path or workspace grant. The retained file tool may disclose only its structured inspection result and a requested bounded excerpt. Built process fixtures verify queue identity, no implicit upload, restart, and no provider replay.
- Standard ACP embedded resources use the same selected-file owner on an attached private stdio connection. The supplied bytes enter the retained store and the URI contributes only a sanitized display name. Separate grants govern any later file or network access. Built process fixtures cover byte identity, scope refusal, and retry after restart.
- Library selection requires an attached private stdio client, negotiated inspection and answer operations, and consent on the identified input. The host checks the session, turn, wait and revision basis before retaining one bounded PNG under that chat. It commits the exact choice before continuation can resolve the image. The host performs no catalog fetch, accepts no path or URL, and issues no new filesystem grant. Later model context keeps the text result without the pixels. Built process fixtures cover the exact answer and restart path.
- The native host enables compatible PNG tool results only for the OpenRouter PNG profile. The adapter validates the tool reply sequence, resolves retained bytes within its request bounds, and correlates the image to its reply in the same provider request. The built child and Main egress fixture verifies the saved key, exact route and one copy of the selected image in the continued request.
- Desktop IPC admits the Library interaction only from the exact workbench route and its attached frame. Main maps an opaque review ID to the captured session, turn, wait and revision basis. The renderer passes an explicit selection as a catalog ID and bounded PNG bytes, or a skip. Main rechecks the frame on return. IPC fixtures cover navigation and attempts to use another attachment's review.
- Native image generation requires the negotiated private Desktop supervisor and a saved OpenRouter or Vercel connection. Main captures the curated model, provider variant, and background capability. Each call supplies a fresh proof from the worker's current captured key. The retained service checks that proof against the key it returns to the image operation, including at dispatch. The proof stays outside the model request and the journal. Replies carry only a bounded receipt, a known generation without retention, or a failure disposition. Cancellation addresses the exact reverse request. The host ends the turn after an unverified delivery and keeps any established generation facts in the summary. Built worker fixture exercises the captured route, restart, and Stop.
- A negotiated generation reference is available for a Library-enabled Act input on the OpenRouter PNG profile. The selection owner verifies the exact current turn's successful Library operation, answer, and retained digest. Main accepts one bounded PNG under the existing private capability, and the retained service verifies the captured provider variant and constructs the inline image input. The tool grants no path or URL access. Built worker fixture covers pause, reopen, and prior-turn refusal.
- A separately negotiated attachment reference binds one exact PNG from the current Act submission to the OpenRouter image route. The native host verifies the retained source and bytes before the reverse request. Main requires a focused workbench confirmation before dispatch. Declining or revoking a review before dispatch sends no image request. Previous turn context and generic file attachments supply no generation reference authority. Built worker fixture covers decline, exact transfer, and prior-turn refusal after reopen.
- A separately negotiated workspace reference starts with a native file capture under the primary workspace's read grant. The capture refuses aliased paths and retains the exact PNG. The generation owner verifies the active turn, read grant, capture operation, typed receipt, and retained bytes. Main reviews the captured source in the focused workbench and keeps its path out of the image service request. Built worker fixture verifies source replacement while paused, exact transfer after reopen, and prior-turn refusal.
- Generated image placement requires an ordinary Act turn and a verified generation receipt from the same chat. Main binds the requested relative path to the selected workspace and existing parent identity, checks the retained bytes against the receipt, and calls the scoped file worker after a native confirmation on the focused workbench. Navigation, teardown, or exact request cancellation revokes the approval. Publication creates one new file atomically. An existing identical regular file can satisfy a retry, while a different file or an aliased destination stays untouched. The artifact stays in Recents after placement fails. Built worker fixture covers a conflicting destination and reuse of the retained bytes after reopen.
- The native image crop tool receives a turn-bound grant to the most recent retained model image owned by the chat; new raster crops use its prepared PNG. Tool authority checks that grant independently from workspace permissions. The scratch owner verifies the retained image digest and working-copy receipt before bounded, atomic replacement. The crop result exposes the copy identity and digest. Process tests verify restart retention, missing-copy refusal, chat isolation, and untouched project files.
- The source-built file intake reads only the selected regular file through a pinned descriptor. The retained owner retains the original and a separate byte-exact copy before acceptance. The inspection tool grants only the accepted task a bounded read of that copy, without a filesystem path argument or workspace authority. The provider receives display metadata and may request a bounded text excerpt through the tool. Process fixtures verify isolation, restart and refusal after loss of either copy.
- Bundled skills are compiled into the native host, so no file exists for the agent's file tools to read and none is extracted or granted. The bundled skill reader returns that fixed text only for a bundled name in the turn's captured skill listing, takes no path, reads no filesystem and has no effects. Tool authority checks its turn-bound grant independently from workspace permissions, and project skills in the same listing are read with the ordinary file tools under the existing grants. Process fixtures cover the read and the refusal of an unlisted name.
- The native artifact read requires negotiated private stdio and an exact attached session. It returns a bounded PNG only when the settled turn's successful crop receipt matches the existing private scratch bytes. The read uses pinned descriptors, creates no files, and exposes no path, digest, or unrelated tool output. Process tests cover reopen, a replaced or missing copy, and refusal across sessions and shared connections.
- The Desktop artifact IPC admits only an artifact listed for the same attachment's latest observed finished turn. Main rechecks the frame, chat, and observation after the read. The PNG response validator validates the bounded byte response against the selected descriptor and returns only bytes. The Desktop fixture verifies restart recovery and missing-file refusal through the built native child.
- Queued input inspection uses the separately negotiated private native routes. The host verifies the exact queued input, owning attachment, and observed session revision before and after reading retained bytes. Each chunk is at most 256 KiB and its original is bounded to 20 MiB. Claimed, withdrawn, replaced, stale and foreign inputs reject without dispatch or mutation. Main's queued display owner replaces hidden transport URIs with bounded opaque selectors scoped to the session, input and revision; IPC additionally rechecks the initiating frame and latest observation after delivery. The existing input inspection reports factual text-only eligibility, so rendering an image does not permit text replacement to discard it. Native process fixtures, Main decoder fixtures and IPC fixtures cover scope, revocation, bounded bytes and observational behavior.
- The retained file exporter publishes a new file exclusively from bounded retained bytes. A window-owned chooser supplies the destination to Main. The chat caller supplies only its attachment, observation and artifact identities, and the Tools caller supplies only its media item ID. Main rechecks the initiating scope before publication. Existing destination files and the retained result remain available after a failed copy.
- The native read-only file adapters revalidate the turn's selected directory against current grants and protected roots. Native path opening uses pinned directory handles and refuses link traversal. File tool tests cover grant revocation and protected files.
- The agent settings file adapter reaches only the host settings file through the settings owner. Permission admission asks for every write and withholds the file unless command denials cover its folder; Desktop approval review admits only that exact write. Permission tests, the headless approval process test and Desktop approval tests cover the ask, decline, invalid content, scope and command coverage.
- The native history extension requires a negotiated operation and an attached source session. The host binds a derivation to committed history and keeps a fork in the source workspace. The portable projection copies visible text with omission evidence and keeps raw tool data, provider state, and grants out of the seed. An edit target resolves the visible anchor to the exact retained text-only submission within the attached chat. Inherited context from another chat cannot authorize a source input read. Native process tests cover attachment, source ownership, and fresh tool permissions.
- Desktop's bounded transcript read rechecks the frame's exact attachment through Main IPC, correlates chunks to the current read, and caps buffered text. The ACP handler requires the negotiated capability, an attached chat, and its workspace. Cursors select only the attached chat's current history view. Reading grants no execution authority.
desktop/src/main/sidecar-sandbox-policy.ts— binds Desktop's strict sandbox posture for the retained sidecar on the daemon's own policy frame: empty direct external egress (no development baseline and no agent provider hosts), host-routed provider HTTP, no generic local bind/connect authority, and an exact read/write grant for the long-lived sidecar's app-managed media root.desktop/src/main/services-sidecar-supervisor.ts— generates the per-spawn password; spawns/supervises the daemon sidecar; captures the native retained-service scope; owns both private channels, forwards the one main-owned media-root fact, and grants no direct provider networking. Windows retains explicitly unconfined non-agent compatibility services with native chat unavailable.desktop/src/main/retained-service-sandbox.tsand its tests — shell-free Seatbelt or bubblewrap launch, executable identity recheck, literal/canonical protected paths, native-ABI seccomp, inherited IPC, denied new sockets and safe owned mask cleanup. Actual macOS and unprivileged Linux ARM64 fixtures cover filesystem denial and Main-transferred connected sockets. Native setup failure has no unconfined fallback on macOS/Linux.desktop/src/main/desktop-entry-window.ts— owns the exact bridge-attached entry window and admits auxiliary native windows only while the authenticated main role is active. Committed quit revokes renderer admission and invalidates queued or in-flight entry reconciliation. The Grida-account transition is additionally bound by GRIDA-SEC-005.desktop/src/main/protocol-router.ts— deep-link protocol guard; the auth callback arm is bound by GRIDA-SEC-005.desktop/src/main/media-root.tsanddesktop/src/main/media-host.ts— one Main-owned app media root and its purpose-scoped adapter. The renderer can list, read, reveal, or save a copy by opaque item ID, or open the fixed library folder. Paths and filesystem details stay in Main. Whole-file reads are serialized, save-copy admits one active picker, and the recent view is capped at 20 records.desktop/src/main/ipc-handlers.ts,desktop/src/main/ipc-sender.ts, anddesktop/src/main/ipc-admission.ts— validate sender frame, window role, pathname and channel before executing OS capabilities. Diagnostics redact URL credentials, query and fragment. Sign-in and onboarding use closed entry-role allowlists. Media library channels require the exact main-role/desktop/toolsroute. Save-copy revokes its admission on main-frame navigation or teardown and rechecks it after the picker and before publication. Custom endpoint changes require the exact Settings main frame; explicit Connect/Save records full-destination consent in protected Main state.packages/grida-daemon/src/daemon-server.ts— lifecycle owner for the same guarded Hono app in either loopback-listening or socketless host-deliveredfetch(Request)mode; shutdown cancels and joins active response streams.packages/grida-daemon/src/http/server.ts— daemon route registration and theDaemonTenantseam behind shared guards; the media tenant frompackages/grida-ai-host/src/media-server.tsis the only tenant.packages/grida-ai-host/src/http/routes/secrets.ts— BYOK key presence/set/delete route group; no key-read route.packages/grida-daemon/src/transport.ts— Basic Auth signing, fetch plumbing, typed HTTP errors, and the daemon route methods;packages/grida-ai-host/src/media-transport.ts— the media tenant client extending it.packages/grida-daemon/src/http/auth.ts— Basic Auth middleware; the header is the only credential carriage. Guard tests and the browser perimeter harness refuse a query-string credential.packages/grida-daemon/src/http/origin.ts— Origin allowlist and host-declared Referer-path guard.packages/grida-daemon/src/auth/file.ts—auth.jsonchmod 0o600 read/write.packages/grida-daemon/src/secrets.ts—auth.json-backed BYOK key store; exposes onlyhas,set, anddeleteto routes.packages/grida-daemon/src/sandbox/policy.ts— daemon sandbox policy frame (secret-path denies and an optional development-network baseline). Desktop builds the sidecar policy from it directly with the development baseline off and no provider hosts, so direct external networking is absent.- editor/proxy.ts — Next.js 16 proxy that sets the CSP +
X-Robots-Tag+Referrer-Policy+X-Content-Type-Optionsheaders on every/desktop/*response. - editor/lib/desktop/csp.ts — the desktop CSP template (
buildDesktopCsp), kept out ofproxy.tsper Next.js 16 route-export rules. Owns the directive set, thegrida-workspace:img/media scope, and the first-party libraryimg-srccarve-out. Pinned byproxy.test.ts. - Library byte locations and their tests — explicit provider selection and validated first-party image origin used by the CSP's Library
img-srccarve-out. They add no connection or provider authority. - editor/app/desktop/layout.tsx — root layout for the desktop route group; gates all children through
DesktopBridgeGate. - editor/scaffolds/desktop/desktop-bridge-gate.tsx — server-rendering-safe gate that renders children only when
window.gridais present. - editor/scaffolds/desktop/open-in-desktop-cta.tsx — fallback shown to web visitors (capability boundary visible per doctrine rule 3).
- editor/lib/desktop/bridge.ts — typed client of
window.grida+ SSR-safe presence detector (useDesktopBridge). - desktop/src/main/host-apps.ts — private desktop UX registry for “Open in…” app detection/opening.
- desktop/src/main/workspace-files.ts — move-to-trash for a workspace entry (file or folder); re-validates that
relPathresolves inside the workspace root, and isn't the root itself, beforeshell.trashItem. - desktop/src/main/terminal-host.ts — human-terminal PTY host: workspace-id-resolved cwd, per-WebContents terminal ownership, per-window PTY cap, kill-on-close; the unsandboxed-by-design surface described under "Human terminal" above.
- editor/scaffolds/desktop/workbench/terminal-pane.tsx — xterm.js view over the
terminalbridge namespace; renderer side of the human terminal. desktop/src/main.ts— Electron main entry; acquires the single-instance lock (deferred toreadyso a secondary instance can forward a macOSopen-filepath viaadditionalDatabefore quitting — before any sidecar/window/IPC is created, preserving the one-sidecar invariant); routesopen-file/open-url/second-instanceopens.- desktop/src/main/open-handoff.ts — pure codec for the secondary→primary "open" forward; tolerant
decodeso a foreign or legacysecond-instancepayload is never mistaken for an open.
The shared provider-file extension also binds ProtectedRoots, its alias tests, and file/workspace grant tests. The existing file/workspace registries consume this common native gate; GRIDA-SEC-014 records custody and the exact protected-root wiring. No file grant or cached handle may admit the shared provider subtree.
What does NOT belong here. A secrets.get method on the bridge.
A bridge installed unconditionally (without pathname scoping). A
daemon that binds 0.0.0.0. An app that loads grida.co's
non-(desktop) routes inside the desktop window without revoking the
bridge first. Any IPC handler in Electron main that acts without
checking event.senderFrame.url. A grida:// deep-link handler that
exchanges OAuth codes itself — the exchange belongs to the same-origin
/desktop/auth/callback route against the webview-held PKCE verifier
cookie (GRIDA-SEC-005). The fixed http://localhost callback for the native
ChatGPT model provider is a separate main-owned ceremony registered under
GRIDA-SEC-008; it must not reuse or widen this Grida-account deep-link arm.
What it protects. Desktop sign-in gives the Electron webview a
first-class Supabase cookie session — the same session shape as a
browser tab, so every existing cookie-gated route and middleware works
unchanged. The ceremony runs in the system browser (RFC 8252; embedded
webviews are blocked by providers) and returns through the
grida://auth/callback deep link. The boundary is the rule that a
grida:// deep link is untrusted, world-invokable input: it must never
be able to create, steal, or redirect a session by itself. Its only
deep-link-controlled navigation is the fixed same-origin
/desktop/auth/callback handoff to the one controller-owned entry window;
the cookie-held PKCE verifier remains the authority for exchange.
Vulnerable scenario (prevented). Custom-protocol URLs are invokable
by any webpage and any local process (open "grida://…"). Without the
boundary: (a) login-CSRF — an attacker mints their OWN authorization
code and fires grida://auth/callback?code=<attacker-code> at the
victim's app, silently signing the victim into the attacker's account so
later work is saved where the attacker can read it; (b) a phished or
replayed single-use code is redeemed by a party other than the app that
started the flow; (c) the deep link is used as a navigation primitive to
walk the privileged (bridge-attached) window to an attacker-chosen URL.
Why it's specifically risky here. The desktop window carries the
window.grida bridge (GRIDA-SEC-004), so a navigation primitive fed by
an unauthenticated OS-level input lands directly on the app's most
privileged surface. And the repo is open source — the exact flow shape,
paths, and params are public, so the design must not rely on obscurity.
How the code prevents it.
- PKCE verifier confined to the Electron cookie jar —
editor/app/desktop/auth/start/route.ts
mints the
@supabase/ssrcode-verifier cookie on a route-handler response (the supabase/ssr#55-safe shape) and returns the same-origin/desktop-authlaunch-page URL carrying thecode_challenge. The sign-in method is chosen on that web page (editor/app/(untracked)/desktop-auth/), and every method binds its GoTrue flow to the forwarded challenge (host/auth/desktop-auth-flow.ts, pinned by its test) — so the desktop never names a provider, and whatever the method, the resultingcodeis exchangeable ONLY with the jar-held verifier: a code minted against a different verifier is rejected by GoTrue (closes the naive login-CSRF); a phished victim code is single-use, expires in 5 minutes, and is useless off-machine without the jar. - The challenge is confidentiality-sensitive in transit — in this
design the
code_challengedoubles as the binding token between "the desktop that started this flow" and an acceptable code: an attacker who learns a victim's challenge can mint a code bound to it for the attacker's own account and fire the deep link at the victim, logging the victim into the attacker's account (login-CSRF via challenge replay — a random attacker challenge is harmless, but the victim's is not). It is unguessable (256-bit) and must not be disclosed, so the launch page lives in the analytics-free(untracked)route group (editor/app/(untracked)/layout.tsx) — no Google/Vercel pageview script ever sees its URL — withReferrer-Policy: no-referrerso the challenge never leaks via aRefererheader either. The insiders redirect target is likewise analytics-free (and dev-only). Address-bar / history exposure is inherent to any browser OAuth handoff and bounded by the 5-min, single-use code; the systematic third-party beacon is what is closed here. - Pure, stateless, fixed-target parser —
desktop/src/main/protocol-router.ts
has no Electron dependency, performs no code exchange, holds no auth state,
and never searches for or navigates a window. It reduces untrusted protocol
input to a closed native intent whose target is the constant
/desktop/auth/callbackpath on the configured editor origin, forwarding only the knowncode/error*params. Main then adds exactly one fixednative_entry=1provenance marker so the hosted callback can distinguish the current entry controller from legacy Desktop 0.0.13; custom-scheme input cannot supply, clear, or duplicate it. The marker is compatibility routing only, never authentication authority. Nothing else from the deep link crosses the boundary, and every branch consumes the URL (no re-queue loop). - Exact entry-window ownership —
desktop/src/main/desktop-entry-window.ts
owns the one canonical sign-in → onboarding → main
BrowserWindow. desktop/src/main.ts gives the parser's closed callback intent only to that controller—never a focused-window, first-window, or URL-matched fallback. The controller re-checks the exact configured origin and/desktop/auth/callbackpath before it hides and navigates its own window. Auth callbacks are control-plane events: while the entry role is booting or sign-in they bypass onboarding and work-file admission. Once onboarding or main is active, stale/world-invokable account callbacks are ignored so they cannot navigate a live workstation away from user work. - Exchange only at the same-origin callback; fixed compatibility handoff —
editor/app/desktop/auth/callback/route.ts
runs
exchangeCodeForSessionwith the cookie client (identical mechanism to the web(auth)/auth/callback). A successful marked callback redirects to the inert fixed completion route, while an unmarked callback preserves Desktop 0.0.13's fixed/desktop/welcomehandoff. Malformed markers fail to the legacy handoff; failure always redirects to the fixed desktop sign-in route. These are the only success destinations: neither route chooses onboarding, a workspace, or a caller-supplied destination. After a current-client exchange, the controller re-probes the cookie session through desktop/src/main/account-session.ts and the fixed/desktop/auth/meroute, combines only the resultingsigned-in/signed-outstate with native non-secret Desktop preferences, and chooses the next role. Before its first authenticated role decision, the current controller may load the fixed, hidden legacy onboarding migration surface once, read only the exact former onboarding boolean, persist that result and a durable migration marker in native preferences, and remove the renderer key best-effort. Renderer storage is never ongoing authority and is never consulted again. A transport, redirect, migration-probe, upstream-availability, or schema failure fails closed; none is evidence that the user is signed out or that migration completed. - Redirect containment; non-navigating sign-out — the
will-redirectguard in desktop/src/window.ts holds server 302s to the same same-origin/desktop/*allowlist as user navigations (will-navigatedoes not fire for server redirects, so without the hook a redirect chain could walk the bridge-attached window off-surface). Blocked redirects are NOT handed to the OS browser. Sign-out is the same-origin editor/app/desktop/auth/sign-out/route.ts: navigating the webview to the web/sign-outwould be blocked andshell.openExternal'd — logging the user out of their OS browser. The desktop route accepts only Electron main's explicitSec-Grida-Desktop-Account-Session: sign-outintent accompanied by browserless Fetch Metadata (Sec-Fetch-Site: none,Sec-Fetch-Mode: no-cors,Sec-Fetch-Dest: empty, and noOrigin). ThoseSec-headers cannot be authored by renderer fetch/XHR/form/service worker code, so a renderer cannot mutate the shared cookie around the controller. The route returns only a non-redirecting204on success; an HTTP response never selects the next native role. - One serialized global sign-out — desktop/src/main/ipc-handlers.ts accepts the account sign-out capability only from the exact Settings path, then delegates to the entry controller. The controller requires the main role and closes every other registered auxiliary window before mutating the shared cookie session. If an existing dirty-window close handler keeps any auxiliary window alive, sign-out aborts while credentials are still intact. Before the cookie mutation starts, the controller synchronously revokes IPC admission from every sender. Only after that close phase succeeds does desktop/src/main/account-session.ts POST to the fixed sign-out endpoint, reject redirects or non-success, treat that success as the irreversible cookie-mutation authority, and transition the same entry window to sign-in. An auxiliary Settings sender may stay hidden only long enough for Electron to serialize its successful invoke reply; it has no admitted IPC role in that interval and main then destroys it. A later account probe cannot roll back cookie deletion or leave the UI presenting a confirmed main role. Reconciliation that independently discovers signed-out state also clears the sidecar's short-lived hosted-account capacity before it hides auxiliary surfaces and presents sign-in.
- Ceremony in the system browser only — the launch URL travels
renderer →
shell.open_external(http/https-validated IPC); the webview never loads a provider page, and the…://auth/callbackredirect is allowlisted in Supabase (supabase/config.toml locally; the hosted project's dashboard in production). The scheme is per-environment: production returns togrida://, while local dev/insiders builds register and return togrida-dev://— so a machine running BOTH a dev build and the installed production Grida never has the two fight over one OS handler. The target is chosen from the build channel (process.env.NODE_ENVin the editor's auth-deeplink.ts;app.isPackaged/insiders in the desktop'senv.ts), never from request input, so it stays a fixed, non-attacker-controllable constant. The router (protocol-router.ts) accepts either scheme with byte-identical fixed-target behavior; the OS only ever delivers a build its own declared scheme.
Electron main holds no durable desktop account or provider credential.
Chromium's default session owns the account cookie jar. The current Supabase SSR
helpers do not configure these cookies as HttpOnly; trusted same-origin renderer
code is not excluded from that cookie authority. This boundary relies on the
fixed ceremony, renderer/navigation controls and native capability separation,
not a renderer-inaccessible cookie guarantee;
the entry account client invokes session.defaultSession.fetch only for the
two fixed same-origin account routes. Main never reads or exports cookie/token
material, and DesktopAccountSession returns only the three-state projection
needed by the entry controller—not the route's account payload. Main persists
only non-secret Desktop preferences separately from every credential store.
Its provider
broker does transiently route BYOK/GG request headers and bodies; the sidecar
owns persisted BYOK material and may hold the purpose-scoped, short-lived
hosted-AI token (GRIDA-SEC-006 — memory-only, renderer-pushed, never a refresh
token). The durable Grida account session is refreshed by the same
@supabase/ssr middleware machinery as the web app. The /desktop/* CSP keeps
connect-src closed, so renderer session reads go through the same-origin
/desktop/auth/me route rather than direct supabase-js calls.
Files bound by this id. Run grep -rn GRIDA-SEC-005 . to enumerate.
Today:
- supabase/config.toml — redirect allowlist entries:
grida://auth/callback(production) +grida-dev://auth/callback(local dev/insiders). The hosted dashboard allowlists only the productiongrida://target. - editor/lib/desktop/auth-deeplink.ts — the single, per-environment
…://auth/callbackredirect-target constant (build-time, never request input). Must stay aligned with the desktop'sDEEP_LINK_SCHEME(desktop/src/env.ts). - editor/app/desktop/auth/start/route.ts — PKCE start; verifier cookie + launch-page URL (method-neutral; the desktop never names a provider).
- editor/app/(untracked)/desktop-auth/page.tsx + editor/app/(untracked)/layout.tsx — the web launch page and its analytics-free root layout. Shares the sign-in shell (editor/components/auth/sign-in-shell.tsx) and Google button (
authorize_urlmode); validates the challenge, binds the offered method's GoTrue flow to it, mirrors the web sign-in's insiders routing (NEXT_PUBLIC_GRIDA_USE_INSIDERS_AUTH→ redirect to the insiders page with the challenge forwarded). Deliberately NOT a(site)sibling:(site)loads Google/Vercel analytics that would beacon the challenge-bearing URL. The(untracked)group must never gain a URL-reporting script. - editor/host/auth/desktop-auth-flow.ts — the flow vocabulary shared by the launch page and the insiders route: challenge validation, challenge-bound authorize/OTP builders, verify-link extraction pinned to the Supabase origin (pinned by
desktop-auth-flow.test.ts). - editor/app/(insiders)/insiders/auth/basic/sign-in/route.ts (+ the hidden
challengepassthrough in basic/page.tsx) — the insiders email+password desktop branch: verifies the password exactly like the web insiders flow, then mints the challenge-bound code by firing the GoTrue OTP and consuming the emailed verify link straight from the local Mailpit capture, so the developer keeps email+password and still traverses the production verify →grida://→ exchange path. A password grant alone can never produce a challenge-bound code (GoTrue returns sessions directly for passwords), which is why the mint rides the OTP-link machinery. Local-only by GRIDA-SEC-002 (/insiders/*404s outside development), which is what makes the Mailpit coupling acceptable (pinned by itsroute.test.ts). - editor/app/desktop/auth/callback/route.ts — the only code-exchange point; routes the fixed native-owned provenance marker to completion and preserves the fixed unmarked Desktop 0.0.13 welcome handoff, always within
/desktop/*(pinned by itsroute.test.ts). - editor/app/desktop/auth/complete/page.tsx — inert, fixed success handoff; contains no routing choice.
- editor/app/desktop/auth/migrate-onboarding/page.tsx — inert, fixed hidden surface on which main performs the one-time exact-key renderer-to-native onboarding migration; contains no migration logic or native capability.
- editor/app/desktop/auth/me/route.ts — no-store, same-origin account projection; distinguishes upstream unavailability from signed-out state (pinned by
route.test.ts). - editor/lib/desktop/account-session-state.ts — shared signed-in/signed-out/unavailable classification for the account projection and protected Desktop server routes; retryable or unclassified auth failures fail closed instead of rendering sign-in (pinned by
account-session-state.test.ts). - editor/app/desktop/_components/account-required.tsx — defense-in-depth projection of that classification onto authenticated Desktop routes; unavailable fails closed instead of rendering an extra sign-in surface (pinned by
account-required.test.tsx). - editor/app/desktop/auth/sign-out/route.ts — native-Fetch-Metadata-gated, non-redirecting sign-out (never renderer-callable and never the web
/sign-out; pinned byroute.test.ts). - desktop/src/deep-link.ts, desktop/src/env.ts, desktop/forge.config.ts, and desktop/scripts/prepare-dev-electron-branding.mjs — closed per-environment scheme vocabulary and registration; production and local/insiders never contend for one handler.
- desktop/src/main/open-handoff.ts + desktop/src/main.ts — collect OS/secondary-instance callback URLs, re-validate them through the parser, and deliver the closed intent only to the canonical entry controller.
- desktop/src/main/protocol-router.ts — stateless fixed-target auth arm; forwards only the closed callback allowlist and then adds the constant native-entry provenance marker (pinned by
protocol-router.test.ts). - desktop/src/main/account-session.ts — fixed-route, redirect-refusing account projection and native-intent sign-out over Chromium's cookie-owning session (pinned by
account-session.test.ts). - desktop/src/main/desktop-preferences.ts — non-secret, versioned native onboarding authority; owns the durable one-time renderer-migration marker, writes are serialized and atomic, future schemas are read-only, and no generic renderer preferences capability exists (pinned by
desktop-preferences.test.ts). - desktop/src/main/desktop-entry-window.ts — exact entry-window ownership, serialized role transitions, one-time fixed-surface onboarding migration, callback re-probe, role-aware blocked-navigation recovery, auxiliary-window admission, and close-before-sign-out ordering (pinned by
desktop-entry-window.test.ts). - desktop/src/main/ipc-handlers.ts + desktop/src/main/ipc-admission.ts — exact sender/role/path/channel validation for the one native account-sign-out transition and narrow sign-in/onboarding IPC capability sets (pinned by
ipc-admission.test.ts). - desktop/src/window.ts —
will-redirectguard;isAllowedNavigationpredicate (pinned bywindow.test.ts).
What does NOT belong here. A code exchange in the Electron main
process. A PKCE verifier carried on the deep link, the bridge, or argv.
A router that navigates to a path taken from deep-link input, forwards params
beyond code/error*, or treats the native-added provenance marker as
authentication authority. A desktop webview navigation to
(auth) routes or the web /sign-out. Sidecar- or main-held SESSION
tokens (the scoped hosted-AI token is the one sanctioned exception,
registered under GRIDA-SEC-006 and the GRIDA-SEC-004 hosted-AI
paragraph). The launch page in a route group that loads Google/Vercel
analytics (or any URL-reporting script) — the challenge in its URL is
confidentiality-sensitive, so it stays in (untracked). Provider OAuth for
the native ChatGPT model provider: its fixed localhost callback, sidecar-held
credential, and model egress are the distinct GRIDA-SEC-008 boundary and never
produce a Grida webview cookie session.
The task spending authority, Goal adapter, private Gateway extension, Desktop egress, and Gateway connection bind optional Goal ceilings to the existing supervised Gateway principal. The capped route, shared request owner, cap parser, and Gateway adapter require the fixed capped request contract before dispatch. An older server refuses that route; there is no uncapped retry. Exact retained allocations cover parent and funded child inference, including compaction. Unknown outcomes keep their holds. Paid or unknown external tool lanes are withheld from capped Goals. Rejected input preflight publishes no allocation; accepted retries cannot recreate missing authority. Desktop displays this evidence through its Goal owner and exact amount parser.
Surface. This is the security half of Grida Gateway (GG) — the
tokensurface. Every file here carries bothGRIDA-SEC-006and its appropriateGRIDA-GGsurface marker; touching it runs thesecurityreview first, then theggsurface skill. The gateway endpoints, theggclient provider, and the desktop token wiring are the other GG surfaces (GRIDA-GG: gateway|provider|desktop), governed by the same skill. Domain spec: Hosted AI.
What it protects. Hosted ("no-BYOK") AI calls from Desktop or an independent native host are
authenticated by a purpose-scoped, short-lived, org-bound JWT — and
by nothing else. The /api/v1/ai/* endpoints never accept a Supabase
access token, a cookie session, or an API key. Desktop's /desktop/auth/token
and native /api/v1/auth/gg use one shared mint owner; each requires its own
live account authentication and verified org membership. The
boundary is the rule that the credential a native process holds for
AI grants only a 15-minute window (with 60 seconds of clock tolerance) of AI calls billed to an org the
user was a member of — and nothing more.
Vulnerable scenario (prevented). A desktop process credential leaks — a log line, a crash dump, a local proxy, an exfiltrated memory snapshot. If that credential were the user's Supabase access token, the attacker gets the user's whole API surface: RLS-scoped database reads, storage, profile — the account, for up to an hour, renewable if the refresh token ever traveled with it. With the scoped token the blast radius is: AI calls, on one org's credit, for the 900-second signed window plus the accepted 60-second clock tolerance, and the token is structurally useless everywhere else (audience check) — Supabase never even sees it.
Why it's specifically risky here. The sidecar is a long-lived local daemon that makes third-party network calls with credentials in memory; it is exactly the process class where credentials leak. And the desktop webview session (GRIDA-SEC-005) is a full first-class login — handing that to the daemon would collapse two carefully separated trust levels into one.
How the code prevents it.
- Two authenticated adapters, one mint policy —
editor/app/desktop/auth/token/route.ts
requires
auth.getUser()and resolves the org through the GRIDA-SEC-003 verified resolver (session fallback, or explicitorg_idthroughrequireOrganizationId→assertOrgMember). The route accepts no org header — no new org-id trust input. CSRF is bounded by SameSite=Lax auth cookies + same-origin-only readability (no CORS on/desktop/*). Its Desktop main projection adds the verified account subject only for the browserless native intent under GRIDA-SEC-005. Native/api/v1/auth/gginstead uses GRIDA-SEC-010's live OAuth verification and an explicit positive safe-integer organization ID. Its fixed membership query retains that exact bearer and filters the verified user and organization in the same statement. Unknown/invisible membership is denied without a service-role read or browser fallback. Both adapters callgg.mint: per-user quota → host-owned member lookup → one signer. Neither mint reads credits or performs provider/billing work. - Scope is cryptographic, not conventional —
the GG token policy signs
HS256 with a dedicated server-only secret (
GG_TOKEN_SECRET), pinsalgorithms: ["HS256"](no alg-swap) andaud: "gg:ai". A Supabase token fails verification structurally (different keys), and this token fails everywhere Supabase tokens are accepted. - 15-minute expiry, 60s clock tolerance — verification requires integer issue/expiry claims, a positive window no longer than 900 seconds, and no issue time beyond the tolerance. Expiry is the unit of revocation; abandoning a leaked token requires no server state.
- Fail-closed secret handling — unset or <32-byte secret →
not_configured→ 503. There is no fallback path to a weaker credential. Rotation viaGG_TOKEN_SECRET_PREVIOUSis verify-only; signing always uses current. Retire the previous key only after the last old-key token's 900-second lifetime plus 60-second tolerance. - Verification is local and exclusive — every
/api/v1/ai/*handler authenticates viaverifyGgTokenonly; none construct a Supabase client from the bearer value (createClientFromBeareris the other pattern, for first-party Supabase tokens on/private/*routes — grep-able invariant). - Custody doctrine (client half) — the Desktop media daemon holds the token in
memory only: never
auth.json, never disk, never a refresh token. The webview session remains the only durable credential (GRIDA-SEC-005); the renderer re-mints and re-pushes. Provider requests use the GRIDA-SEC-004 host transport: Electron main necessarily observes the scoped bearer header and request body in transit, but does not retain, persist, return, or log them and never receives the durable webview session. The native chat connection instead retains its own scoped grant in main memory. It obtains the grant from the account owner through the fixed cookie-authenticated mint. Sign-out and a detected subject change invalidate its authority. Refresh retains the same origin, subject, and organization. The connector adds the bearer only to the fixed chat route through the dedicated provider session. The child receives no bearer or account cookie through that connection. The reviewed default model may receive a user-selected retained PNG on that route. The native resolver verifies its owner, identity, size and digest before dispatch. Other Gateway model and origin combinations do not gain image input from this profile. The connector requests Gateway billing evidence on that same chat POST. The chat route emits a terminal observation only for an authenticated Gateway execution with a matching job request ID. The native Gateway adapter checks that identity against the observed response header and binds the evidence to the captured scope. Pending observations carry no amount. On opted-in native chat streams, the route bounds the terminal billing read and cancels it with the caller. An unavailable read leaves the original inference finish and usage intact and a valid receipt pending. The early request ID remains available on cancellation, and generic compatible endpoints have no Gateway receipt decoder. The private billing lookup resolves the retained request ID from one attached session's exact inference attempt and compares its original authority with the current Gateway scope. Main uses the current scoped grant for a bounded fixed jobs GET. The response exposes settlement status and a verified amount, and leaves the original inference receipt intact. Turn summary reads a bounded projection of retained evidence under the same scope. The renderer receives local operation and attempt identities. An explicit refresh must match an eligible row in the current attachment's latest settled turn, its exact funded review, or an indexed child assignment. The worker resolves the review through the parent operation's committed claim and checks the same Gateway authority. Main revalidates the parent attachment before lookup and before returning the result. Named-child billing uses an owner-projected index of accepted inputs to their exact source turn. Its bounded pages expose local assignment identities, names, dispositions and settlement evidence, without upstream request IDs or credentials. Main requires a refreshed assignment to match an eligible row on its current page; the worker checks the exact attached parent, source turn, assignment, attempt and original Gateway authority before resolving a request. Unattributable historical work is marked incomplete. Reading a summary does not request settlement or run inference. The neutral source index supplies exact lookup without owning credential policy. General workers retain the exact accepted task-spending selection and share its existing ledger and total ceiling; a new worker cannot mint a budget. Worker composition and funding regressions preserve that selection alongside the original provider authority. Host attribution and process tests cover child reuse, source scope and the retained index; the Desktop Gateway tests cover page-bound refresh and attachment changes. Independent native hosts keep their own account custody under GRIDA-SEC-010. The fixed exchange delivers a frozen GG grant only to a construction-time trusted synchronous memory sink; its public result contains only org/expiry metadata. The sink invocation is acceptance under profile authority: logout before it prevents handoff, while later logout cannot recall a grant. A sink failure cannot undo a token it already retained. The initial native auth consumer uses one fixed model-list request and discards the grant. Reusable memory custody and image/video/music/Tripo feature execution live in@grida/ai; native command composition remains separate from the account exchange. The Rust CLI obtains one scoped grant per generation command through that fixed exchange. Its synchronousrequest_gg_withcallback constructs invocation-owned media authority while the account profile lock still fences acceptance. Account JWTs never enter media execution or its HTTP transport. GG commands inspect no BYOK environment keys. The immutable Rust grant carries the verified session subject and configured API origin for consumers to bind their execution authority. Completion drops invocation authority; it neither persists, refreshes nor automatically re-mints a GG grant. CLI destination and output controls are independently registered under GRIDA-SEC-013. The native CLI agent obtains its initial scoped grant through the same synchronous handoff. Its session selection binds the registered API origin, verified account subject, organization and model. Only a matching live authority can prepare the fixed chat POST. The CLI HTTP owner checks expiry again after connection setup and before sending. Before expiry, an owned renewal uses only the captured scope. The account owner checks the registered origin and current stored subject before any credential refresh or mint. The mint verifies membership in the original organization. The live connection retains its binding across renewals within this scope. Shutdown waits for any accepted renewal custody work within its existing deadline and reports unverified cleanup on timeout. The shared media/provider host composition owns exactly one GG store for all mounted media and optional agent routes. Stopping that composition clears its store after the daemon drains active requests. Restarting can reuse the existing BYOK file but requires a newly pushed GG grant; switching startup modes neither copies nor persists that grant. Shared GG URL admission requires HTTPS except URL-parsed loopback hostslocalhost,127.0.0.1and[::1]. Media constructors, text URL construction, liveness checks and hosted POST helpers use the same policy before reading custody. Userinfo, query and fragment are refused; API path joining cannot switch origins. Hosts still own destination grants, DNS/address validation and redirect decisions; this does not change custom BYOK endpoints. - Mint rate limit —
rl:v1-ai:mintper-user sliding window (fail-open when Upstash is unconfigured; the billing gate on the AI endpoints is the actual spend control). Both mint routes use the samerl:v1-ai:mintkey space and 10/user/60s quota, not separate host allowances. When configured, the shared owner rejects the SDK's five-second timeout allowance and upstream failures before membership lookup or signing. Both hosts return a safe 503; actual quota exhaustion remains 429. The deadline bounds the quota decision, not Redis work, which may finish later and consume quota. Late completion cannot resume minting, and no automatic remint occurs. - Funded 3D input references have separate authority — the four fixed POST
routes under
/api/v1/ai/3d/areuploads,model-generation,rig-checkandrigging. Each authenticates the current GG bearer and applies its user quota before bounded JSON processing and verified-org execution. Upload preparation gates credit eligibility before using server-onlyGG_TRIPO_API_KEYat Tripo's fixed/v3/files/presignendpoint. It returns a signed object PUT URL and a 900-second upload ticket, never the provider key. The ticket usesaud: "gg:tripo-upload", HS256 and a domain-separated HMAC-derived key; signing uses the current GG configuration and previous-key verification supports rotation. A ticket cannot authenticate an AI call, and a GG bearer cannot replace a ticket. Execution independently verifies the ticket's signature, lifetime, subject, organization and image/mesh type against the live bearer. Raw file tokens, input URLs and extra reference fields are refused. The ticket binds declared media type and byte length (20,000,000 bytes per image; 60,000,000 bytes per mesh). This is not server verification of the actual S3 object: the provider's presign API accepts format, not an enforced size or content hash. The native SDK bounds the bytes it uploads, while direct hostile HTTP clients remain subject to Tripo's storage/input validation. The only upload destination is HTTPStripo-data.s3.us-west-2.amazonaws.com; PUT carries no GG/account/provider credential, and redirects are refused. Tickets and signed upload URLs are transient and do not enter generated-media receipts. Server generation consumes only the verified refs, with actual usage metered under GRIDA-SEC-003. Self-contained GLBs are bounded to 64 MiB and returned as aligned base64 chunks in streamed JSON; provider URLs never become result authority. Server execution has a 600-second deadline, hosted native calls a 780-second deadline, and the Node route's configured maximum is 800 seconds. These limits do not make accepted provider jobs durable or cancel them. - Funding choice and recovery do not cross accounts — Desktop explicitly
selects organization credit or Tripo BYOK and checks the matching native
tripo_gg/rigging_ggcapability. Expired GG authority can be refreshed once only when no accepted task identity is present; known task IDs fence that retry, including Electron's safe message projection. Other errors do not switch funding or resubmit. Native GG execution uses the shared memory store and does not read BYOK credentials; the CLI obtains a scoped grant through its existing explicit-organization exchange and clears it after the command. - Discovery does not carry execution authority — anonymous public GG
metadata describes supported current interfaces. Native image/video/music
submission uses the fixed Grida API
/api/v1/ai/operationsbridge, which verifies the org-bound scoped JWT and selects the upstream operation itself. Original job status uses/api/v1/ai/jobs; it remains retrievable after a catalogue change. The JWT never goes directly togateway.grida.aior to a result URL. Music/video references are downloaded only through the bounded, credential-free asset lane. A failed poll or asset read never authorizes a second paid submission, a credential fallback or an organization change. Validated accepted job IDs remain in safe music/video errors. Music session refresh resumes that exact job with GET-only reads, without depending on current catalogue membership. Job retrieval has its own per-user abuse budget; it does not consume discovery or submission allowance.
Residual risks (accepted, documented). Org-membership revocation is not re-checked within a token's 900-second window plus clock tolerance. The mint rate limit fails open without Upstash. In-flight AI requests at sign-out complete on their token rather than being aborted — expiry is the revocation mechanism. Electron main and any OS-trusted TLS-inspection proxy can observe the short-lived bearer while transporting a request; neither is a durable account-credential holder. Upload tickets are reusable by their original subject and organization during their short lifetime; they identify content and grant no credit or one-shot job reservation. Unobserved Tripo terminal usage is the accepted synchronous billing limitation tracked in KI-BILL-005.
Files bound by this id. Run grep -rn GRIDA-SEC-006 . to enumerate.
-
Portable Rust provider contracts: crates/grida-ai/src/catalogue.rs, crates/grida-ai/src/lib.rs, crates/grida-ai/src/media.rs, crates/grida-ai/src/tripo.rs, crates/grida-cli/src/http.rs, crates/grida-cli/src/http_tests.rs. These preserve this boundary. Rust conformance adapters, where present, are feature-gated and excluded from the distributed executable.
-
Native chat composition uses the account owner, CLI adapter, typed grant, host authority, and streaming HTTP owner. The native process proof exercises a scoped run, concurrent ACP renewal, owned shutdown, an explicit authorized organization change for new idle input, and refusal to change the organization of retained accepted work.
-
Native context compaction uses the same runtime inference and grant checks as a conversation turn. Recovery may refresh an undispatched request within its captured provider principal and scope. It retains interrupted attempts without sending them again. Provider-reported context pressure is attributed to the exact retained request, provider, principal, scope and model before it can trigger a later input's compaction.
-
Windows provider composition tests — optional BYOK discovery preserves existing GG eligibility without swallowing custody errors.
-
Funded 3D HTTP owner and binding tests, upload-ticket owner and custody tests — exclusive live GG auth, subject/org/type-bound references and bounded request/streaming responses; also GRIDA-SEC-012.
-
Tripo execution seam, billing tests, server transport, and egress tests — fixed provider key authority, public DNS pinning, terminal receipts and billing; also GRIDA-SEC-003.
-
Tripo generation client, rigging client, rigging discovery, task transport, GG adapter and adapter tests, with the existing bounded invocation — explicit funding, credential-free signed uploads, validated receipts and no paid resubmission; also GRIDA-SEC-004.
-
Model-generation route, rigging routes and funding tests — the same composition-owned GG store behind native admission, safe task IDs, and no BYOK fallback; also GRIDA-SEC-004.
-
Desktop funding/session adapter and recovery tests — explicit funding, capability-aware readiness and one pre-acceptance token refresh.
-
CLI rigging composition and funding tests — explicit org selection, scoped memory-only authority and cleanup; also GRIDA-SEC-013.
-
Public SDK exports, operation discovery, shared route eligibility, and discovery tests, and native parser parity tests — GG route facts grant no scoped token, organization authority or credits.
-
Host media error mapping — preserves actionable expired-GG and insufficient-credit codes from safely projected operation failures. BYOK adapters cannot pass arbitrary upstream codes through as GG authority.
Every file below also carries the GRIDA-GG surface marker (token /
gateway / provider / desktop); the gg skill
governs the surface, this record governs its security half.
- Media server entry, shared media/provider host, media server tests, and built-entry isolation tests — a single memory store feeds the existing GG routes and operations and is cleared on composition cleanup. Historical full-agent fixtures consume that same store but are not distributed.
- Desktop composition and its tests — forward the editor origin and provider transport into the media composition; the startup choice grants no additional token authority.
- Retained host public exports — hosted-session DTO exports remain type-only; the memory store and its credential reads stay in the host/provider layer.
- Desktop media startup proof — synthetic GG push/use/clear/restart through the real sidecar channels; confirms the token is absent from persistent BYOK state and logs without minting or spending a real grant.
- GG owner, policy, configuration, and contract — one policy with injected clock/key/quota capabilities, one configured server binding, one environment reader. Tests pin the binding, policy and configuration.
- editor/lib/auth/gg-token.ts — compatibility exports only; existing compatibility tests still test those exports.
- Native mint route, binding and tests, member query and tests — live native account authority and explicit current membership; also GRIDA-SEC-010/012.
- Native auth lifecycle, Node factories, public export, lifecycle tests, Node tests, and contract — fixed mint transport and guarded memory handoff; independent account custody remains GRIDA-SEC-010. Credential-store tests also pin invalid sink configuration before durable I/O.
- Rust native grant handoff and fixtures — project account and destination binding from the authenticated session and fixed registration during the memory-only exchange.
- CLI account host and host tests, media composition and composition tests — fixed native exchange into invocation-only GG authority, no BYOK reads on the GG path, and cleanup without credential output. Account custody remains GRIDA-SEC-010; CLI media egress and artifacts remain GRIDA-SEC-013. The installed proof uses synthetic account/GG endpoints and checks the distinct bearer on each route, safe output, and media preflight before minting. It replaces the retired TypeScript CLI media harness, whose archive and Node preload assumptions cannot verify the native executable. It does not verify hosted minting, token cryptography or provider execution; the ongoing proof contract retains those limits.
- Local fixture bootstrap, native probe, browser consumer proof, and production HTTP proof, with the fixture guide — fresh test-only GG authority and bounded, memory-only access verification. Their infrastructure isolation remains GRIDA-SEC-011/012; no generation or provider call is required.
- editor/app/desktop/auth/token/route.ts — the mint route (pinned by its
route.test.ts). editor/app/(api)/(public)/api/v1/ai/**— the hosted GG endpoints: OpenAI-compat chat/completions + models, Grida-native image/video/music generation and the four 3D feature routes. Verify withverifyGgTokenEXCLUSIVELY; provider work is gated through the seam, and metered operations use actual receipts (pinned by route and seam contract tests).editor/app/(api)/(public)/api/v1/models/catalog/route.ts— deliberately OUTSIDE the glob above, and deliberately unauthenticated: older installed hosts fetch the schema-1 compatibility catalogue before any session token exists. It accepts NO credential (strictly stronger than accepting the wrong one), spends nothing, and returns only catalogue data already public on the models page. Listed here so it is not "fixed" into the token-gated family, which would break the boot fetch. See catalogue distribution.- editor/lib/ai/openai-compat/ — the wire codec + error envelope + allowlist + rate limits. The allowlist test pins anonymous current GG discovery without importing provider factories for a model-list read.
- HTTP image adapter tests — shared scoped GG execution behind existing host admission; expired authority and insufficient-credit status remain actionable.
- Standalone package proof, cleanup/report tests, runtime guard, image consumer, video consumer, music consumer, and guide — synthetic memory-only GG grants and fixed fake responses; proves package/credential routing without minting a real token or contacting a provider.
- Shared GG session store and its tests — memory-only custody, 30s expiry slack and credential-free status. The retained host path re-exports that owner. Hosts supply the scoped grant; the SDK does not acquire or persist an account session.
- Shared GG request helpers, URL admission tests, image adapter, image operation, provider entry, and SDK contract — one URL admission policy before per-request scoped-token reads, tested through each media consumer and public helper.
ImageClientguarantees safe failure codes and exposes only generated content and provider/model descriptors. The lower-level GG helpers construct body-free 401/402/status errors but can propagate raw transport or parsing failures; their callers must apply an operation error boundary. Its contract tests pin credential replacement/expiry, explicit provider selection and safe failures. - Current discovery, its tests, generic JSON client, client tests, Grida API bridge and bridge tests — anonymous metadata is separate from organization-scoped submission and original-job recovery. The bridge chooses a fixed served path; caller data cannot select an origin, credential or organization.
- Shared video operation, music operation and their video / music tests — current GG JSON contracts use one scoped submission and retain its original job identity. Status reads stay on the Grida API origin; validated video/MP3 references use the bounded credential-free asset lane. Clearing custody blocks later authorized calls without recalling accepted work. No polling or download failure retries generation, mints authority or reads a BYOK credential. The shared invocation retains cancellation/deadline cleanup, and host routes retain admission, persistence and safe status mapping.
- packages/grida-ai-host/src/http/routes/gg-auth.ts —
/auth/gg/set|clear|statusbehind the daemon perimeter; token never logged (pinned by its test). - The
ggmedia resolver arms (resolve-image, resolve-video) — precedence: explicit wins; implicit BYOK →gg. The/secrets/*allowlist keeps REJECTING theggid (no key may be stored under it; pinned bygg-auth.test.ts). - desktop/src/main/provider-network-host.ts — destination-bound Chromium transport; transiently carries the scoped Authorization header without persistence or renderer exposure.
What does NOT belong here. An AI endpoint that accepts Supabase
access tokens or cookies. A mint path without a live session or without
membership verification. The token (or a refresh token) persisted by
the daemon, main process, or auth.json. A signing fallback when the
secret is unset. A parallel mint policy or signer behind a new host adapter.
What it protects. The native agent discovers skills and project guidance
by reading directories that may be attacker-controlled — a checked-out repo's
.claude/skills / .agents/skills and AGENTS.md, and the host-bundled skill
tree. The boundary is the rule that a skill lookup or capture can only ever
read files inside a skill directory it legitimately resolved within the
already-readable project root, no matter what a hostile skill dir names or
links to.
Vulnerable scenario (prevented). A user opens (or clones) a repo whose
.claude/skills/ contains a directory named to escape (../../../etc), a
skill dir that is a symlink to /, a SKILL.md symlinked or hard-linked to
~/.ssh/id_rsa, or an AGENTS.md linked out of the project. Without the
boundary, discovery or capture would read those files into the model's
context.
How the code prevents it.
- Name validation before any path is built — the
native catalog rejects any skill name
that is not lowercase ASCII letters, digits and
-starting with a letter, so.., absolute paths, and path separators never become a skill name. - Native project authority — a local one-shot invocation pins its explicit project root. ACP discovers project guidance only inside the primary root of a host-supplied profile with read access already allowed. A client-provided working directory alone selects bundled skills. The native reader opens fixed names relative to a pinned directory, refuses links and nonregular files, and bounds document reads. The accepted snapshot carries text and provenance. A newly captured project skill also carries a labeled workspace-relative directory derived from its validated name and layer. It grants no tool access and follows no companion paths; later supporting-file reads use the ordinary workspace authority. A turn with workspace file tools also captures the catalog's names, descriptions and sources with its input; the model reads a listed project skill through those same file tools.
Files bound by this id.
- Native catalog and capture, native document reads, project authority, permission profile, and native process fixtures, and delegated skill-read cases.
What does NOT belong here. Following a link out of a skill tree.
Accepting a skill name with a path separator. Reading a SKILL.md or
AGENTS.md from outside the pinned, already-readable project root.
What it protects. Grida Desktop can use an eligible ChatGPT subscription as a native text-model provider. Grida still owns the agent loop, prompts, tools, approvals, sessions, and persistence; this path does not launch Codex, Codex app-server, or an ACP agent. The localhost OAuth callback completes only the exact attempt opened by Main and the credential owner. Credentials stay on the trusted side of the renderer bridge. Provider traffic uses fixed auth and inference destinations. Stored conversations keep their provider selection when ambient readiness changes.
Vulnerable scenario (prevented). A webpage or local process races a forged request into the fixed callback port and consumes the legitimate user's one-time attempt; a compromised renderer asks the bridge for access/refresh tokens; a late refresh for account A overwrites a newly connected account B; sign-out loses a race and a late exchange resurrects the deleted credential; an upstream error body containing provider details is serialized into the agent stream; or connecting ChatGPT silently moves an existing BYOK conversation onto a different cost/privacy boundary.
Why it is specifically risky here. Native-app OAuth client ids and loopback redirect URLs are public, localhost HTTP endpoints are reachable by webpages and local processes, the refresh token is long-lived, and the privileged renderer is hosted at a web origin. Electron main must also transiently transport token and inference bytes because the sandboxed sidecar has no direct provider egress. None of those components may be treated as trusted merely because it is “local.”
How the code prevents it.
- Two-owner OAuth ceremony. Electron main binds the callback before
browser navigation, on only the approved ports (
1455, then1457) and both available loopback families. The credential owner generates the one-use attempt id, random state, and PKCE S256 verifier/challenge for that exact redirect URI. Main accepts only boundedGETrequests for the exact/auth/callbackpath andlocalhost:<bound-port>Host, constant-time compares state, leaves the attempt usable after a mismatched callback, atomically claims one valid callback, and closes every listener/socket on success, denial, timeout, cancellation, or failure. Browser success is not rendered until token exchange and durable persistence complete. - Exact browser-open validation. Before
shell.openExternal, main requires the exacthttps://auth.openai.com/oauth/authorizeorigin/path, client, scope, response type, S256 challenge shape, configured product parameters, and the state and redirect URI of the currently bound attempt. Reserved parameters must occur exactly once; credentials, fragments, an alternate approved port, unknown query keys, and lookalike origins fail closed. - Secret custody and race-safe persistence. The selected credential owner
performs code exchange, refresh, account lookup, and request-time injection.
Ordinary macOS/Linux Desktop and disposable native subscription launches
use one Main-owned instance after Main fixes its native chat paths.
OAuth remains in daemon
AuthStore(auth.json,0600, atomic replacement). Updated macOS/Linux writers share a cross-process lock with API-key retirement under GRIDA-SEC-014, rereading before mutation and preserving unrelated records. BYOK moves to the separate shared TOML owner; new API-key writes throughAuthStoreare refused on macOS/Linux. Windows retains its host-local API-key/OAuth backend and in-process writer queue, with strict disk reads before mutation. Provider set/delete cannot replace or remove an OAuth record. Windows privacy relies on inherited native ACLs, not POSIX mode bits; it does not support shared BYOK. Refresh is single-flight and rotating refresh tokens are persisted before use. Compare-and-replace/remove guards prevent a late refresh or cancelled exchange from overwriting/removing a newer account. Exact attempt cancellation and a generation invalidation make sign-out win over in-flight exchange/refresh work. - Narrow renderer capability. Guarded IPC and the optional
window.grida.chatgptnamespace expose only connect, cancel, status, and sign-out. Electron main reconstructs the returned status DTO field by field; authorization URLs, codes, PKCE material, access tokens, refresh tokens, and raw token claims have no renderer type or route. Renderer status reads are epoch-ordered so an old read cannot visually restore a signed-out or previous account. - Pinned provider traffic. Desktop grants, through a Main-only provider
grant the sidecar never receives, only the exact OpenAI token
endpoint and ChatGPT Responses endpoint to the authenticated provider lane;
neither is a provider-asset/download grant. The captured native transport
sends only to the configured Responses route, injects bearer/account/product
headers only at request time, forces stateless Responses posture, and
permits at most one refresh/replay after
401within the captured account and connection. Reconnecting the same account creates a new connection. Legacy records without a connection ID can refresh only their exact captured record. It consumes every non-success body and returns only a bounded status before the native agent can observe it. The native broker captures an opaque scope from the persisted account and sign-in lineage plus the configured registration and exact Responses route. It accepts the selected stateless request shape and rereads that lineage before dispatch. Rotation can refresh the same connection. Records without a lineage require sign-in before native selection. OAuth execution uses the strict disk reader shared by credential mutations and ignores the generic test environment override. Failed Responses return bounded status, request identity, and retry timing without upstream response bodies. The private native launch carries the opaque scope and selected model. Its stdio transport grants only the exact generation route and sends no credentials. The in-process Desktop owner exposes the OAuth ceremony as direct start/complete/cancel/status/sign-out calls (no HTTP route or in-process router), bounds their string inputs, and injects the selected token and account headers at the provider edge. Ordinary Desktop offers the closed compatible model set through its normal connection catalogue. Product membership and the default are authored once indata/ai/chatgpt-subscription.json; generated TypeScript and Rust finite wire maps use the pinned Models bindings. Retired IDs permit reading saved metadata only, grant no execution, and remain unavailable until explicitly replaced. A saved subscription choice hashes the captured connection scope and exact model; it contains no credential. Main recaptures and compares that binding before admitting its native worker. Refresh keeps the connection identity; a new sign-in invalidates earlier choices. The renderer receives only a recommended choice for untouched new chats and preserves explicit selections and accepted work's captured authority. The opt-in profile continues to use the reviewed default model. Signing out withdraws workspace admission and waits for the native children and custody work before replacement. Grida account sign-out releases the workspace without deleting the separate subscription. App shutdown joins exact OAuth attempt cancellation and outstanding custody within a bounded wait. Ultra reviewers reuse the parent's captured subscription execution and exact broker. They receive no OAuth material or broader destination grant. Their request shape still omits unsupported wire output-token bounds; the native harness reserves generation steps and bounds time and response bytes without claiming to impose a provider-side quota ceiling. - Accepted work keeps its provider authority. The native host captures the model, provider principal and scope when it accepts work. Continuations, retries, queued inputs, compaction and its recovery refuse with a conflict when the live launch authority or provider differs, rather than moving accepted work onto another credential or cost boundary. Automatic titles run as a temporary, tool-free request through the same launch's provider execution; a failure leaves the chat untitled. Changing provider is an explicit user selection, never a fallback. A new idle request may explicitly select another provider or principal while retaining the durable transcript. The product host projects earlier portable conversation without replaying private provider state under an incompatible route. The protocol adapter retains its strict replay-binding validation.
- No credential borrowing and no ACP fallback. Grida never reads
~/.codex/auth.json, browser cookies, or another app's credential store. ChatGPT auth failure never launches or selects Codex ACP. The daemon mounts no ChatGPT auth/provider routes and constructs no credential manager. Main's coordinator calls the dedicated native subscription host directly, parses every result field by field and forwards only a safe error code. Exact destination grants and the secret-free renderer contract are unchanged.
Current experimental trust posture. The implementation follows the public
Codex/Zed-compatible native flow: unless
GRIDA_CHATGPT_OAUTH_CLIENT_ID supplies a replacement, Desktop uses the
public Codex native client id, with originator=grida, and exposes a closed
static model allowlist. That client/backend identity and the allowlist are not
a documented general third-party OpenAI contract; support, terms, model
availability, and a stable Grida registration remain release gates outside
this repository.
Account metadata is accepted only from the successful response of the exact pinned HTTPS token endpoint (or from a token payload delivered in that response), after state, PKCE, and code exchange. Token payload parsing checks shape and expiry but does not independently perform JOSE signature, issuer, audience, or nonce validation. The security claim therefore rests on the authenticated token-endpoint response, not on generic OIDC JWT verification. A future claim source outside that response must add full cryptographic OIDC validation before use.
Long-lived OAuth material currently uses the daemon's owner-only atomic file store, not an operating-system keychain. This prevents renderer/network exposure and cross-write races but does not protect against another process already running as the same OS user. Moving refresh-token at-rest custody to a platform credential store is a separate hardening step.
Files bound by this id. Run grep -rn GRIDA-SEC-008 . to enumerate.
-
Windows credential compatibility tests — platform-selected host-local custody and preserved OAuth records, with strict failures. These simulate platform selection with disposable files; they do not certify native Windows ACLs. The load-bearing groups are:
-
desktop/src/chatgpt-configuration.ts,desktop/src/main/{oauth-loopback-callback,chatgpt-oauth}.ts,desktop/src/{provider-network-policy,services-sidecar,preload}.ts,desktop/src/bridge/contract.ts,desktop/src/main/ipc-handlers.ts, anddesktop/src/main.ts— fixed configuration, callback/orchestration, exact network grants, sidecar construction, guarded bridge, and shutdown. -
Desktop composition, its tests, and built media-entry isolation tests — retained-service startup never constructs a chat provider; the dedicated native subscription host owns credential use.
-
Native subscription custody and its ceremony tests, Desktop host adapter, native process launcher, private egress, and Rust subscription transport bind one private launch to an exact OAuth connection and the fixed Responses route. Process fixtures exercise the ceremony and scoped continuation with synthetic responses.
-
Native chat host, its portable history projection, compaction and automatic titles, and the continuation owner — rule 6: a chat's captured provider authority is rechecked before continuation, retry, compaction and recovery, and titles use the same launch execution.
-
Desktop composition, subscription profile identities, ordinary subscription selection tests, and the custody process fixture connect the guarded ceremony to the selected provider owner and verify withdrawal and drain at sign-out and shutdown.
-
packages/grida-ai-host/src/protocol/{chatgpt,provider-ids,endpoints}.ts,providers/{chatgpt-credentials,chatgpt}.ts, andsrc/index.ts— safe vocabulary, OAuth lifecycle, captured native transport, and public type projection. -
data/ai/chatgpt-subscription.json,scripts/ai-catalogue/{generate,projection}.mjs, andcrates/grida-agent/data/chatgpt-subscription-models.json— explicit subscription membership, generated finite adapter mappings, and retired metadata IDs kept separate from execution permission. The generator's regressions reject stale copies, invalid defaults and unsupported bindings. -
packages/grida-daemon/src/auth/file.tsandpackages/grida-daemon/src/http/server.ts— shared race-safe credential persistence. -
packages/grida-desktop-bridge/src/index.tsandeditor/lib/desktop/{bridge,chatgpt-subscription}.ts— secret-free renderer contract and ordered status cache. -
The adjacent
*.test.tsfiles tagged with this id pin callback replay and bounds, authorization correlation, cancellation/sign-out races, credential rotation/reauth races, safe error mapping, native request shape, bridge DTOs, and renderer ordering. -
docs/wg/ai/agent/chatgpt-subscription-provider.md,docs/wg/desktop/{agent-security,process-model}.md,desktop/docs/chatgpt-subscription-oauth.md, andpackages/grida-ai-host/docs/chatgpt-subscription-provider.md— normative and implementation bindings.
What does NOT belong here. A renderer method that accepts or returns token, code, verifier, raw claim, or authorization-URL material. A generic localhost listener, callback path, redirect, provider origin, download grant, or arbitrary fetch. Cookie scraping, importing Codex credentials, direct sidecar egress, silent provider fallback, unbounded/replayed callbacks, upstream response bodies in errors, or treating ChatGPT sign-in as Grida account sign-in, an OpenAI API key, Codex app-server, or ACP.
What it protects. The optional Library importer holds a Supabase
service-role key and executes SQL through psql. It may target only the
Supabase stack started for this checkout: exact host 127.0.0.1, the API and
database ports declared in supabase/config.toml, and each endpoint's expected
scheme and shape. Environment variables, command-line URLs, and caller-supplied
keys are never destination authority.
Vulnerable scenario (prevented). A developer has production Supabase values in the shell or copies a hosted DSN and key into a seed command. The fixture importer then writes hundreds of assets and catalog/vector rows into production with RLS-bypassing authority.
Why it's specifically risky here. This is a bulk, idempotent-by-content-hash fixture importer, not an application request. It uses service-role Storage calls and direct SQL, so an accidental remote destination would have a large blast radius and ordinary RLS would not contain it.
How the code prevents it.
- Destination credentials and endpoints come only from
supabase status -o json, run at the discovered repository root. - The expected API and database ports come from that checkout's
supabase/config.toml; missing or malformed configuration fails closed. - API and database URLs are validated independently against canonical
127.0.0.1endpoint shapes.localhost, IPv6 and alternate loopback addresses, wrong schemes/ports/paths, URL overrides, queries/fragments, and remote or lookalike hosts are rejected. - Local service-role HTTP requests use a proxy-disabled opener and reject
redirects. Direct SQL strips inherited libpq
PG*connection settings, so neither environment can redirect a validated loopback URL. - The destination is validated before archive resolution or download and before the Storage/SQL writer accepts it.
- Adjacent tests pin the accepted local shape, negative cases, write-layer revalidation, transport isolation, and fail-before-download ordering.
Files bound by this id. Run grep -rn GRIDA-SEC-009 . to enumerate.
Today:
- .agents/skills/opt-library/SKILL.md — operator contract.
- .agents/skills/opt-library/scripts/seed.py — configuration parsing, exact endpoint checks, command ordering, proxy/redirect isolation, libpq environment isolation, and write-layer revalidation.
- .agents/skills/opt-library/scripts/test_seed.py — positive, negative, and ordering regression tests.
What it protects. A registered first-party native application obtains its
own Supabase OAuth account session. Browser consent does not export the
browser's session, and a loopback callback cannot establish identity by itself.
Native identity/account reads and /api/v1/auth/gg accept only configured OAuth
clients through the configured issuer. Desktop cookie custody (GRIDA-SEC-005)
stays separate. Native minting exchanges this account authority for GG's scoped
AI credential (GRIDA-SEC-006); gateway endpoints never accept the account token.
Vulnerable scenario (prevented). A callback substitutes another account or destination; a forged consent POST approves an unseen client or scope; or a cookie, GG token, ordinary browser token, or forged JWT is treated as native account authority. Sharing Desktop credentials or using global logout would also let the independent native client disturb another application's session.
Why it's specifically risky here. A public OAuth client ID identifies a registration, not a trustworthy binary. The native host deliberately holds an account credential with the user's existing permissions. Identity scopes are not an account-data sandbox, and this credential must not become an agent/GG credential through reuse of an existing browser or daemon bridge.
How the code prevents it.
- Server-owned authority. Issuer, allowed client IDs, web origin, and exact
callback URIs come from server configuration. The required
GRIDA_OAUTH_ISSUERpins the canonical Auth issuer independently of the same project's Data API origin (NEXT_PUBLIC_SUPABASE_URL), which may use a replica or load balancer. Neither JWT claims nor hostname rewriting selects either destination. Bearer preflight requires the exact issuer,authenticatedaudience, expiry, user/session IDs, and an allowed client ID. Decoded JWT claims are not identity: the same token must then succeed at the fixed issuer's/oauth/userinfo, whose subject must match. Cookies are never a fallback. Issuer calls reject redirects, bound response size/time, and return safe errors. - Bound browser intent. Consent requires the configured incoming HTTP Host before reading the browser session or issuer authorization. GET navigation need not carry Origin. A decision additionally requires the configured browser Origin, a bounded form, and a ten-minute signed proof binding user, authorization, client, callback, and scope. The pending details are read again before mutation. Supabase owns approval, denial, and one-use code issuance; Grida issues no account token. Existing-consent redirects may omit details, but must still target an exact configured native callback; native exchange and bearer APIs independently enforce client identity.
- Contained ceremony. Consent stays in the analytics-free layout, with
configured no-store, frame denial, and
strict-originreferrers: authorization paths and query values are excluded, while same-origin form POSTs retain their Origin header.no-referrercan turn that Origin intonullunder the Fetch Origin-header algorithm. The decision redirect and native callback retainno-referrer. Native login binds a registered127.0.0.1port before browser launch, uses fresh state and S256 PKCE, and accepts one exact callback. Wrong state, path, host, method, or duplicate parameters cannot consume the pending ceremony. Cancellation, denial, timeout, and completion close the listener. Code and refresh grants use the fixed OAuth token endpoint; credential-bearing requests never follow redirects or acquire browser cookies. - Independent native custody.
AuthClientreturns safe metadata; only the injected custody/transport capabilities receive account tokens. This account lifecycle reads no Desktop, browser, provider, or daemon credential store. The separate@grida/auth/providersentry owns API keys under GRIDA-SEC-014; sharing private-file and lock primitives does not share account authority. Its single-writer lifecycle serializes mutations, rejects overlapping login and refresh, and invalidates stale work on logout/cancellation. Accepted refresh rotations survive a later identity-check failure; the access token and identity remain the last verified values until that check succeeds. Logout clears this custody before remote work. It constrains the captured JWT to the configured issuer/client/user and a non-nil session ID; missing session targeting cannot reach an issuer fallback to account-wide logout. Expired or near-expired logout performs at most one detached refresh in memory and requires the same session binding. It never persists the renewed credentials or emits signed-in metadata after clearing. Live identity verifies the selected bearer before requesting onlyscope=local; failed remote revocation is reported rather than changing to global/grant revocation. Only completed 200/204 responses confirm logout; their bodies are discarded. - Durable profile authority. The Node and Rust custody owners bind a private profile to canonical home, issuer, client ID, and API origin. Keyring is the initial default; explicit file selection is remembered. Backend failure never selects another store. Keyring writes require exact read-back, established entries cannot disappear into a signed-out result, and logout retains a secret-free revision. File custody validates ownership, permissions, links, and macOS ACL grants; atomic replacement never publishes partial JSON. Backend migration records intent before copying credentials and blocks auth until old-backend cleanup completes. Pending migration resumes explicitly.
- Cross-process mutation authority. Every coordinated lifecycle mutation, including verification and empty logout, shares one profile lock and advances its durable revision. Login captures a revision before consent and compares it on commit, without holding a lock during browser interaction. SQLite OS locks release on process exit; acquisition times out without stealing a running lock. The lock carries no credentials and never rolls back completed custody writes. Accepted rotation survives later identity failure. Unpublished temporary credential files are cleaned under authority, never adopted.
- Fixed native account transport.
requestAccountowns credential-bearing requests to the configured API origin:organizations.listaccepts only an optional positive safe-integer cursor;credits.readrequires a positive safe-integer organization ID. There is no arbitrary URL, method, header, user selector, token getter, or caller-installed operation. The package validates bounded ordered pages and credits with a matching organization, explicit cache states, safe integer amounts, valid timestamps and consistent gate fields. Extra fields are discarded; failures expose safe codes. Billing policy remains server-owned. Near-expiry refresh and result acceptance share coordinated custody; accepted rotations survive read failure. HTTP failures are never replayed. Same-instance logout fences pending reads; another process's logout is ordered after any read already accepted under the profile lock. Accepted data and already-sent remote work cannot be retracted. - Membership-scoped organization reads. The enforcing account adapter
verifies the live native bearer before creating a database source with that
exact Authorization value and the same configured project's publishable key.
The fixed GET selects only
id,name,display_namefrompublic.organization; existing membership RLS decides visibility. No cookie client, service role, RPC, browser organization preference, or caller-selected user is involved. Exact RLS-visible counts and validated ascending IDs preserve page continuation despite a lower database row cap. Zero visible rows succeed explicitly; database failures and malformed/incomplete results never become empty accounts. - Passive credits retain membership authority. The issuer live-verifies
the native bearer before the fixed Platform credit transport. It forwards
original native authority only as
X-Grida-Native-Tokenwith the separateplatform.grida-ssrworkload credential. Platform checks current canonical membership and permits native authority only on the passive credits route. The adapter validates matching org, unknown-versus-zero state, original cache time, exact safe integers, and gate fields before returning the published DTO. Missing configuration, denied membership, or malformed/incomplete results never become a balance. No source financial-view fallback, provisioning, refresh, or provider call occurs. A display projection cannot authorize paid execution; an already-authorized read is not instantaneous revocation. - Fixed scoped-GG exchange.
requestGgAccessaccepts only an explicit positive safe-integer organization ID and posts to the configured API origin's/api/v1/auth/gg. A missing construction-time memory sink fails before custody or I/O. The package validates and freezes a bounded grant matching that org, with expiry in the future and at most 960 seconds from its clock. It rechecks expiry before invoking the captured synchronous sink under the same custody and generation authority as account reads. Only the sink receives the GG token; the public result contains organization/expiry metadata. Neither account custody nor storage gains a GG token. Logout before invocation fences delivery; a later logout or throwing sink cannot recall an accepted grant. There is no automatic replay, remint or weaker credential fallback. The server independently verifies the live OAuth bearer and explicit current-user membership before the shared GG mint policy signs a token. - Thin CLI account host. Account commands select the public hosted
registration pinned in the executable: fixed HTTPS issuer/API, client ID and
registered loopback callbacks. No environment or repository configuration
changes hosted destination authority. Custody uses the canonical Grida home
or an explicit absolute
GRIDA_HOME, with issuer/client/API profile binding. The bundledsb_publishable_...project key supplies admission only on the fixed issuer logout request, alongside the user bearer. It is not identity; key rotation does not create a different credential profile. Secret/service keys and legacy JWT keys fail configuration validation before custody. Empty/relative overrides and filesystem-root/user-home targets fail before custody. The explicit local fixture file remains bounded and owner-controlled, accepts only the fixed local issuer/API and registered callbacks, and requires a separate home outside ordinary Grida home, including filesystem aliases. Invalid local configuration never falls back to hosted authority. The host discovers no dotenv/repository configuration, Desktop cookies or provider keys. Browser launch uses a fixed OS executable with a constructed environment and one validated authorization URL argument, without a shell orBROWSERoverride. Explicit manual login writes that URL only to stderr. Noninteractive reads never start login. The fixed command grammar delegates to public auth/account owners; JSON and terminal output contain safe DTOs or classified failures, never arbitrary exception objects. Help, version and docs do not open custody or network. Cancellation closes pending login but waits for noncancellable custody work, reporting that a write may have completed. Media commands' BYOK inputs and shared provider store are separate under GRIDA-SEC-013/014 and are never consulted by account custody. Native GG generation consumes the fixed scoped handoff in rule 10, not an account-token getter.
Limits and adoption gates. Producer tests are not deployment certification.
The real local Auth 2.196.0 consumer proof has passed login/denial/consent reuse,
code replay rejection, bearer credential rejection, rotating refresh, seeded
organization RLS, and session-local, grant-wide, and account-wide revocation.
The public native organization-page operation also passed the real local API/RLS
proof: separate users see their own organizations, a temporary non-owner
membership becomes visible and then disappears with the same native token, and
the copied package lists organizations across process restarts.
The credits extension passed member/outsider/removal reads, direct REST isolation,
unprovisioned and unobserved cache versus zero, the shared gate's boundary cases,
and unchanged cache snapshots around each read. The account client and copied
auth/account packages also passed explicit/sole-member selection and credits
across process restarts. Subscription billing remains outside this milestone.
The GG extension also passed against local Auth 2.196.0 and PostgreSQL
15.8.1.085: native OAuth mint, GG-only model-list access, cross-user and
removed-membership denial, revocation, and copied-package restart/remint with
unchanged billing snapshots and no persisted GG grant. An accepted grant retained
its documented expiry window. Neither this local result nor offline checks
substitute for hosted routing verification and the ingress assumptions under GRIDA-SEC-012. A model-list
result establishes access, not credit eligibility or provider readiness.
It also passed separate-process restart using a copied package and disposable
test custody. This verifies the local fixture and that test adapter; separate
durable custody tests exercise the Node storage and cross-process contract.
The local proof uses Next.js development mode, whose page renderer replaces
HTML Cache-Control with no-cache, must-revalidate. Consent remains
force-dynamic with configured no-store; the actual hosted HTML header must
be verified before deployment. JSON identity and consent decision responses
retain no-store and are asserted by the local proof.
The deployed issuer must enforce signature verification and live-session
rejection on userinfo, with session-local logout proved against its actual
version and gateway. Client registration remains administrative; dynamic
registration is outside this boundary. Durable custody currently supports local
macOS/Linux filesystems; Node custody requires a main-thread host. Rust CLI
blocking work retains the same SQLite authority through settlement. Windows
account custody and worker-thread Node custody fail closed. The OS, dependencies, and same-user process are trusted;
keyring storage does not isolate credentials from authorized same-user code.
Native keyring access may prompt and cannot safely be cancelled mid-write. A
crash between issuer rotation and saving can require login. Post-rename sync
failure may report failure after a complete write; it never rolls back a spent
token. Filesystem backups/snapshots are outside local cleanup guarantees.
Explicit file recovery of uninitialized metadata cannot clean untracked keyring
entries after manual metadata loss; deleting profile files is not logout.
Existing web/Desktop global logout may revoke native
sessions, and other APIs may accept already-issued JWTs until expiry. Native
OAuth retains the user's existing account authority beyond the CLI command
vocabulary; neither identity scopes nor client-side transport restrict existing
database/API permissions. Organization listing uses existing RLS. Other account,
billing, and GG operations still need their own server authorization; identity
verification supplies none implicitly. Organization pages observe current
membership separately, without a snapshot guarantee across page requests.
The former TypeScript CLI remains in Git history. Reviewed golden CLI cases, current TypeScript SDK consumers and frozen custody fixtures retain the ongoing contracts without building or executing the retired CLI. The obsolete TypeScript archive preparer, installed proofs, Linux smoke and CLI Node preloads were removed after native cutover: they depended on the retired package manifest, and their interception could not constrain a Rust process. Their historical results remain in Git; they are not current acceptance gates. The native installed proof exercises the current executable directly, while the real local-issuer proof below covers the independently provisioned OAuth service. Neither certifies hosted deployment.
Files bound by this id.
-
Native installed OAuth proof and guard tests — the real native CLI against an explicitly owned local issuer, isolated custody and fixed fixture origins. Test setup never grants arbitrary issuer or production authority.
-
Native implementation and synthetic cross-language verification: crates/grida-auth/README.md, crates/grida-auth/src/conformance.rs, crates/grida-cli/src/account_tests.rs, crates/grida-cli/src/http_tests.rs, scripts/cli-contracts/auth-driver.mjs, scripts/cli-contracts/auth-keyring.test.mjs, scripts/cli-contracts/auth-macos.mjs, scripts/cli-contracts/auth-macos.test.mjs, scripts/cli-contracts/auth-linux.sh, scripts/cli-contracts/auth-process.test.mjs, scripts/cli-contracts/cli.mjs. The frozen account-v1 contract and custody bytes check historical profile binding, file/keyring envelopes and logout tombstones against the current owners without native credential access. These preserve this boundary. Rust conformance adapters, where present, are feature-gated and excluded from the distributed executable. The native keyring gate exercises the production logout tombstone and revision contract across all four TypeScript/Rust process pairings, with exact native readback after restart. The fixture creator cleans up only its uniquely bound disposable entries; cross-application item deletion is not account custody. macOS checks require explicit opt-in and allow local applications to access newly created, uniquely labelled synthetic entries. This verifies custody bytes and lifecycle, not application-authorization policy; macOS signing partitions and keychain locks may still prompt. Cleanup matches the fixture's unique label as well as service/account. Developer runs change no existing item, default/search preference, or global access policy. The separate macOS CI wrapper requires explicit opt-in and GitHub-hosted runner metadata. It creates a private synthetic keychain, snapshots and temporarily changes only that disposable runner user's default/search preferences, and verifies its owned marker and selected keychain before starting native operations. Exact fixture label/service/account/path selectors constrain partition changes to confirmed created items. The wrapper terminates its owned test process group before restoring preferences and removing the keychain; unconfirmed process termination retains the private keychain for runner disposal. Cleanup failures fail the gate, and abrupt cancellation relies on disposable VM destruction. Pure tests check guards and command/cleanup scope without OS credential calls; actual unattended behavior requires qualification by the hosted macOS workflow.
-
editor/lib/auth/oauth-server.ts, bearer.ts, and oauth-consent.ts — configured authority, issuer verification, consent proof, and callback policy. Configuration separation and fail-closed validation are covered by oauth-server.test.ts.
-
Native CLI grammar, safe failure types, process entry and output — offline parsing and safe errors, checked by adjacent Rust tests and shared cases. Native host, account composition, command runtime, safe domain errors and HTTP enforce the same shipped/local registration and fixed account routes.
-
Rust account custody: client, configuration, custody, keyring, private native files/locks, wire projections and entry. Blocking mutations retain their SQLite guard through publication; CLI joins them before reporting interruption.
-
Consent page, decision route, and identity route — browser and native entry points. Their producer tests are oauth-bearer.test.ts, oauth-consent.test.ts, and oauth-web.test.tsx.
-
Shared native HTTP owner and shared bearer data transport — one live authenticator, safe HTTP envelope and bounded public-schema REST reader for the fixed account/GG adapters; covered by their adapter and data-source tests.
-
Account HTTP adapter and its tests — the identity binding owns live bearer verification, input/output validation, bodyless HEAD/OPTIONS, and safe errors. Machine request dispatch is separately governed by GRIDA-SEC-012.
-
Native GG route, GG adapter and tests, member query and tests — fixed account-to-GG exchange, shared live verification and explicit same-user membership; also GRIDA-SEC-006/012.
-
Organization route and route tests, account projection and projection tests, RLS data source and data-source tests — native authority reaches fixed user-scoped reads without cookie or privileged-client dependencies.
-
Credits route and route tests, native Platform adapter and tests, fixed billing transport and tests — passive Platform projection with original native authority, exact DTO validation, and no source financial fallback; also GRIDA-SEC-012.
-
Historical credits-view migration and schema record retain source history. They do not define current runtime credit authority.
-
Analytics-free layout and response headers — retain GRIDA-SEC-005 while also protecting this consent ceremony.
-
Native lifecycle, Node adapter, and public export — independent host contract, loopback, transport, and secret custody; pinned by lifecycle tests and Node tests. The package contract records both custody modes and their limits.
-
Credential store, keyring adapter, private files, and profile lock — durable custody, backend transitions, file protection, and crash-released authority. Adjacent tests are store, keyring, files, and lock.
-
Persistent native consumer exercises the public package from isolated subprocesses. The build configuration retains standalone file-mode consumption and leaves native keyring loading lazy.
-
The local auth workflow also runs the native custody suite on macOS/Linux, with an owned-entry macOS keyring smoke.
-
The local consumer proof and copied-package probe also obey the separate local provisioning boundary, GRIDA-SEC-011.
-
CLI OAuth client registration, CLI host and host tests, command lifecycle and lifecycle tests, process entry, grammar and grammar tests, output and output tests — fixed operations, independent custody, explicit browser launch, and safe presentation.
-
The installed native proof checks manual callback login, account reads, cancellation and local logout with synthetic local endpoints and private custody. Hosted registration is pinned by the host tests; neither is hosted OAuth enforcement evidence.
-
CLI launcher and contributor contract select a prebuilt native executable without credential access and document the hosted deployment/acceptance gates. The real-issuer proof contract describes native file custody across local login, restart, concurrency, reads and logout, without injecting an application clock; fixture isolation is GRIDA-SEC-011.
-
Auth lifecycle tests and persistent auth tests exercise controlled-clock refresh/logout behavior separately from installed CLI acceptance. The mixed-process contracts exercise TypeScript/Rust custody and serialized refresh with synthetic sessions.
-
Native package installation proof and native release workflow verify the bundled archive and installed launcher across the release matrix, including Alpine; they do not establish real-issuer or keyring support on every target.
What it protects. The OAuth proof provisions and stops only its owned,
disposable grida_auth_test fixture. Its tooling does not inherit hosted
credentials, linked-project state, or the ordinary editor environment.
GRIDA-SEC-010 separately governs the account authority exercised by the proof.
Vulnerable scenario (prevented). A developer or CI run accidentally uses an inherited Supabase token, linked project, Docker context, or dotenv file to provision against the wrong infrastructure; cleanup stops another local stack; or a test emits credentials through browser artifacts. This harness exercises administrative OAuth registration and real account sessions, so ordinary test defaults would cross those boundaries.
How the code prevents it.
- Fixed fixture authority. Configuration pins project, origins, callback allowlist, and tool versions. State validation checks canonical private paths and the reviewed TOML hash. CLI calls use an explicit workdir and Unix Docker socket, with no login, link, hosted management, or stop-all operation.
- No ambient credentials. Child environments are constructed from scratch
with a private home. Only allowlisted repository migrations and seed are
copied; linked metadata and ancestor dotenv files are refused before CLI
use. Editor snapshots exclude dotenv and generated files and load only
fixture settings. Outputs use a
0700directory and0600secret files. - Owned lifecycle. A fixture lock and state identity gate inspection and
cleanup. Start refuses occupied fixture ports, containers, or volumes;
stop names only the owned project and uses
--no-backup. - Explicit local registration. Bootstrap uses only the fixed local API
and does not follow redirects. It checks the actual Auth image/version,
issuer discovery, and disabled dynamic registration, then creates or reuses
a fixture public client with
token_endpoint_auth_method=noneand exact callbacks. Public client configuration excludes administrative credentials. Bootstrap creates fresh independent consent and GG signing secrets in the private fixture output; neither is inherited from the developer environment. - Contained proof execution. The dedicated editor uses Node fetch/TCP guards; the consumer restricts browser and fetch destinations to exact fixture origins. Its dedicated runner disables traces, video, screenshots, and service workers; the ordinary runner excludes this test. The standalone probe uses private disposable custody and safe IPC results. Its scoped GG recipient holds the grant in memory for one fixed same-origin model-list request and discards it; it exports no account/GG token through IPC. Fresh fixture signing authority is separately governed by GRIDA-SEC-006. Offline configs skip env loading. CI verifies the downloaded CLI checksum, supplies no hosted credentials, cleans up only its fixture, and uploads no credential artifacts. The installed native CLI proof verifies the candidate's single archive and all eight bundled executable hashes, then installs offline into a private tree. It selects production file custody explicitly before session access, captures manual authorization URLs only in memory, and supplies the fixed local registration to the production native host. It does not open the OS keyring. Reports contain hashes and safe phase metadata only; owned browser/profile/process cleanup precedes report writing. This installed proof does not intercept native network calls or inject an application clock. The separate current auth-package probe advances its own application clock to exercise detached logout renewal without modifying issuer time, tokens or credential files. The auth fixture explicitly asserts the logout admission key and its absence on other account requests; the more permissive local gateway alone cannot prove hosted key admission. Both captured and renewed refresh tokens must fail after logout, while another native session and the browser remain usable.
Limits. This is local provisioning, not hosted deployment certification. The executable, repository, dependencies, Docker engine, and same-user process environment are trusted. The retained auth-local Node guard allows other loopback ports and Unix sockets and is not an OS network sandbox. Native CLI destination admission belongs to the production host and HTTP adapter, not this guard. The retired TypeScript CLI proof and its preloads were removed because their package and interception assumptions do not apply to the native executable. The harness checks executable versions; checksum verification belongs to release acquisition and CI. Public container image downloads remain necessary. The original injected-custody probe does not prove durable product storage. The separately installed CLI proof exercises the production file backend and cross-process lock on its recorded platform; it does not certify an OS sandbox, hostile-local-user protection, hosted registration, the system browser launcher, or OS keyring availability.
Files bound by this id.
-
Native installed OAuth proof and guard tests — the real native CLI against an explicitly owned local issuer, isolated custody and fixed fixture origins. Test setup never grants arbitrary issuer or production authority.
-
guards.mjs, stack.mjs, and config.toml — destinations, ownership, environment, lifecycle, and registration.
-
editor.mjs, network.cjs, and native-probe.mjs — isolated hosts. discovery.mjs supplies anonymous synthetic model, endpoint and operation documents on loopback; it rejects execution, credentials and request bodies. A latched loopback-only verdict is checked by CI after both proofs; cleanup cannot hide a prior violation. No public Gateway request is needed.
-
guards.test.mjs, network.test.mjs, discovery.test.mjs, and consumer proof — adjacent verification.
-
Dedicated Playwright config, ordinary Playwright config, offline Vitest config, CI workflow, and harness contract — execution and adoption.
-
Installed native proof contract — separate native processes and production file custody using this fixture's registered client, with explicit limits on expiry, keyring and network-isolation evidence.
What it protects. /api/v1 requests cannot acquire browser authority or be
handled as tenant pages through the shared Next.js web pipeline. Newly bound
account and funded 3D routes select an operation whose adapter supplies authentication and
HTTP policy; declaring a route does not let its author silently omit those rules.
Native account credentials remain GRIDA-SEC-010; GG credentials remain GRIDA-SEC-006.
Vulnerable scenario (prevented). A web redirect or maintenance page replaces an API response; cookie refresh mutates a machine caller's session; host-based tenant routing intercepts an API path; or a route declares account authentication but exports its own unguarded handler. A shared helper can also accidentally pull browser cookies, UI code or request-global state into account operations.
How the code prevents it.
- Early, explicit machine dispatch.
proxy.tsclassifies the reserved namespace before importing browser maintenance, cookie, tenant or Desktop dependencies.policy.tsaccepts configured Host authorities only, ignores forwarded host claims, and admits registered paths only. Unknown paths, unsupported hosts, encoded aliases and noncanonical casing receive safe 404s. Invalid configuration and explicit API maintenance receive safe 503s. These responses are uncached, carry no cookies or redirects, and grant no identity. - Pre-proxy routing is part of the boundary.
next.config.tsreplaces automatic trailing-slash redirection with its web-only equivalent and excludes the reserved namespace from the existing generic web connect redirect. The shared namespace pattern covers percent-encoded ASCII aliases too. Config tests match actual header/redirect/rewrite rules against API paths; the local production-mode proof also exercises real Next routing and web positive controls. - Bindings enforce authority.
operations.tsis the complete inventory.account.tsandgg.tsaccept only their implemented operations. The sharednative.tsowner validates the declared credential/response policy and verifies the live OAuth bearer, validates and projects identity fields, rejects input on the input-free identity operation, and owns all seven method exports. HEAD retains authentication; OPTIONS discloses only allowed methods. Rejected methods and input never call the issuer. Empty-body inspection has a deadline and rejects actual payloads. Organization listing accepts only a canonical cursor and projects bounded pages. Credits require a canonical org ID, query a fixed membership-scoped view and return a passive projection. Both create the RLS source only after verification, preserve that exact bearer and ignore browser defaults. Native GG mint accepts only POST with one explicit JSON organization ID; bodyless OPTIONS declares its methods, while GET/HEAD and other methods are 405. The parser rejects extra/duplicate fields, query input, malformed UTF-8, invalid media/encoding/length declarations and noncanonical IDs before issuer work. It bounds route-entry body reads to 1024 bytes and one second. The shared REST transport retains the verified bearer and uses the independently configured same-project Data API origin, never a destination derived from the Auth issuer; the mint's member query filters that user and organization together before the GG owner signs. Authentication, parsing, membership and signing failures keep the native no-store envelope. The separategg-mediabinding admits exactly the four/api/v1/ai/3d/operations under GRIDA-SEC-006; it does not use native account authentication. Routes export only its fixed seven-method template, Node runtime, dynamic execution andmaxDuration = 800. Only POST executes; bodyless OPTIONS advertises methods, and all other methods return 405. GG verification precedes per-user quota and the 64 KiB/one-second JSON body reader. Query arguments, content encodings, malformed UTF-8, invalid length declarations, unknown fields and unauthorized upload refs fail without provider execution. The native SDK validates operation-specific controls after reference substitution. Results are no-store JSON with no-referrer/nosniff headers; 64 MiB GLB bytes are encoded in aligned chunks rather than one buffered base64 response. - Source checks reject drift.
audit-api.tscompares real App/Pages route placements with the inventory and verifies the complete native binding AST. New handlers cannot use the seven pinned legacy GG/catalogue exceptions. Resolved import traversal checks API/account/GG owners, including aliases, re-exports and installed package runtime entries, for Next/React, browser/UI, dynamic-loader and environment-ownership violations. Invalid fixture trees prove the checks fail. The API workflow runs on every PR without path filters. The GG extension pins its four paths, credential family, POST/OPTIONS policy and complete binding AST. Exactly one reviewed dependency edge is exempted from the browser-free API traversal:lib/api/gg-media.ts→lib/ai/gg-three-d.ts. That named execution owner passes the verified org into the existing GRIDA-SEC-003 billing seam, whose privileged billing/provider graph is reviewed separately. This is not a generic graph exemption: direct browser imports in the GG adapter and account/API imports of the execution seam still fail the audit. The AI seam's independent import audit and lint rules restrict portable SDK execution to its exact owners. - Runtime proof stays local.
scripts/api-localbuilds a private production Next snapshot from the real API, proxy and config sources. Its synthetic loopback Auth and Data servers reject crossed service requests; web tripwires verify two-user identity/cache separation, credential rejection, method/input errors, configured hosts, API maintenance, organization pagination and failure semantics, and production insiders gating. The GG extension uses a fresh synthetic signing key with the real mint and model-list implementations, including credential-family separation and missing-signing-configuration cases, without a credit query or provider call. Its synthetic database exposes rows for the exact bearer only; this exercises request wiring, while real Supabase RLS is proved separately. It constructs the child environment, copies no dotenv/session files, bounds requests/process waits and removes owned source/build/listeners. Application network guards reject unowned destinations; no hosted credentials or uploaded artifacts are required.
Limits. This protects the managed namespace and binding conventions; source
checks are not a sandbox against malicious repository authors. Existing GG and
catalogue handlers remain explicit legacy bindings with their own credential,
streaming, error and cache contracts. Fixed native operations currently cover
identity, organization listing, cached credits and GG access. The separate funded
3D binding owns its described HTTP/authentication/input policy; provider execution
and billing remain GRIDA-SEC-003/006, including the synchronous limitation in
KI-BILL-005.
Next may normalize malformed repeated
slashes or backslashes with a redirect before proxy; the machine response
contract applies to paths admitted by that framework parsing layer.
Next.js 16.2.6's Node proxy clones POST bodies in next-server.js and awaits
requestData.body.finalize() before route entry. In body-streams.js, that
finalizer awaits the original stream's endPromise. The application's
1024-byte/one-second mint parser therefore does not bound pre-route upload
buffering or upload time. Managed Vercel deployments rely on the platform's
request-size limits and slow-client protections for this shared ingress layer:
Vercel documents a 4 MB Routing Middleware body limit,
a 4.5 MB Function payload limit,
and pre-routing Slowloris defenses.
These are hosting assumptions, not guarantees implemented by the mint parser.
The application promises no particular network upload deadline; a function's
execution timeout does not establish one. Deployment checks must confirm the
intended hosting/routing path. Self-hosted deployments must supply their own
ingress size and slow-client controls before exposing the application.
The local HTTP proof replaces unrelated web services with tripwires and uses a
synthetic issuer. It does not certify the full web build, actual Supabase
cryptography/RLS, those web modules' import side effects, or deployment routing.
GRIDA-SEC-011's real local OAuth proof remains separate. The runtime, repository,
installed dependencies, native build tools and same-user host are trusted;
application network hooks are not an OS sandbox. Hosted verification remains a
release requirement.
Files bound by this id.
- API guide, inventory, policy, and policy tests.
- Funded 3D binding, HTTP contract tests, upload references and reference tests — scoped GG auth, subject/org custody, bounded inputs and streamed output; also GRIDA-SEC-006. The four routes are uploads, model-generation, rig-check and rigging.
- Account adapter, adapter tests, and identity binding — also GRIDA-SEC-010.
- Shared native HTTP owner and shared bearer REST transport — fixed bindings share authentication, response policy and bounded reads; also GRIDA-SEC-010.
- Native GG binding, adapter and tests, member source and tests — explicit native authority and member lookup before the shared GRIDA-SEC-006 token owner; also GRIDA-SEC-010.
- Organization binding, operation tests, account projection and tests, and RLS data source and tests — also GRIDA-SEC-010.
- Credits binding and operation tests, native Platform adapter and tests, fixed transport and tests — also GRIDA-SEC-010.
- Proxy, dispatch tests, Next config, and routing tests.
- Source audit, audit tests, offline configuration, and CI workflow.
- HTTP proof, network guards, guard tests, and proof guide.
What it protects. An independent grida process consumes explicit BYOK keys
or a scoped GG grant and writes generated media to a user-selected local directory.
Provider data cannot choose credential destinations or output filenames. Account
credentials stay with GRIDA-SEC-010; GG's cryptographic scope stays with
GRIDA-SEC-006. This is a CLI host boundary, separate from the Electron renderer,
sidecar channel and OS sandbox in GRIDA-SEC-004.
Vulnerable scenario (prevented). A generic fetch path sends a provider or account credential to a result URL or a redirected/private address; repository configuration silently supplies authority; malformed input reaches a paid operation before local validation; or a provider filename overwrites a chosen local file. Raw provider errors, prompts or credentials could also enter terminal output or generation receipts without a fixed projection.
How the code prevents it.
- Explicit inputs and shared operation rules. The fixed grammar requires a
provider/model and explicit input/output directory for generation. JSON input
and friendly request-building flags are exclusive; duplicate fields and competing
stdin readers are rejected. Media flags select only a compatible advertised
variant and never discard media or change provider/model. Scalar parameters
use the published field type, then the same normative SDK parser as JSON. It
accepts no literal key argument, custom provider origin or raw provider-option
passthrough.
--key-stdincannot share stdin with JSON/text or select GG. BundledMediaOperationsdescriptors and the SDK's normative parser establish the exact executable route and validate JSON before credential custody is opened. Ordinary listing/inspection needs no credential or network. An availability filter reports key presence or cached organization eligibility explicitly; neither establishes provider access or generation success. - Invocation-owned credentials.
ProviderCredentialsreads the five named process environment slots (OPENROUTER_API_KEY,AI_GATEWAY_API_KEY,FAL_KEY,ELEVENLABS_API_KEY,TRIPO_API_KEY), an explicitly allocated stdin key, or the shared provider owner under GRIDA-SEC-014. Execution inspects only its selected provider; provider status may inspect all five. There is no dotenv, repository, legacy Desktop file or account-store lookup. Stdin replaces the matching environment slot; successful explicit inputs bypass constructing or opening the stored-key owner for that provider. Missing inputs use the shared file; blank/malformed explicit input fails without fallback. All selected file/environment/stdin keys use the shared AI provider admission policy: bounded to 4 KiB, normalized, header-safe, free of known template values, and checked against documented first-party formats without guessed suffix lengths. Vercel AI Gateway legacy keys remain opaque where upstream specifies no retirement contract. Stdin has a cancellable 30-second bound. Only the trusted SDK key reader receives secret strings. Status projects presence and source and plaintext storage mode; disposal drops private references. Explicit configure/remove commands mutate shared custody without opening account auth. GG obtains an org-bound grant through the auth owner's guarded fixed exchange into invocation-owned media authority without opening a BYOK reader. The media transport never receives the account JWT. - Destination-bound egress. The native HTTP owner admits credential-bearing requests
only on its reviewed provider host/path/method allowlist, with provider-specific
header families. GG permits only the invocation's selected origin: the shipped
public registration's HTTPS API origin or the fixed local fixture, with only
image/video/music generation POST paths and the four exact
/api/v1/ai/3d/{uploads,model-generation,rig-check,rigging}POST paths, with no query parameters. Current GG discovery additionally admits anonymous GETs to exactlyhttps://gateway.grida.ai/v1/models,/v1/endpointsand/schemas/operations.json, with no authority, query or body. The current operation bridge accepts POST/api/v1/ai/operations; original jobs use GET/api/v1/ai/jobswith only a validatedrequest_idquery. Provider redirects are rejected without replay. The download lane is HTTPS GET/HEAD with no credential, cookie, body or caller-selected Host header. Each connection and download redirect resolves fresh DNS, rejects the entire answer if any address is non-public, and pins one validated address for the native connection while retaining the original TLS hostname and certificate verification, including hosted GG. The explicitly selected local GG fixture is the sole private-address exception. Direct requests use no ambient fetch, proxy agent, cookie jar or pooled connection. Header/body sizes, DNS/connect time, total request lifetime and streamed responses are bounded; SDK-specific limits may be lower. The hosted 3D request alone receives a 780-second lifecycle allowance. The separate native agent transport admits the exact GG chat-completions POST at the grant's registered origin. It reuses address validation, TLS and HTTP framing, and bounds the live stream by bytes and deadline. Its billing receipt opt-in has a single fixed header value on that POST. The terminal evidence must match the dispatch request ID and captured scope. The media lane retains its separate routes. The separate signed-upload branch permits only HTTPS PUT totripo-data.s3.us-west-2.amazonaws.com, anapplication/octet-streambyte body of at most 60,000,000 bytes, and harmless content headers. It accepts no Authorization, cookie or provider-key header and follows no redirect; GG authority remains on the selected GG origin. No failed paid request is automatically resubmitted. Standard DNS64 addresses under64:ff9b::/96are admitted only when their embedded IPv4 address passes the same public-address rules. Translations of loopback, private and other denied IPv4 ranges remain denied; one denied address still rejects the whole DNS answer. Other translation prefixes gain no exception. - Input and output preflight; publication. Explicit UTF-8 JSON/text file/stdin
input is bounded to 16 MiB. Selected local images have an 8 MiB per-file bound,
a 16 MiB aggregate read bound, and structural PNG/JPEG/static WebP header checks.
The assembled JSON is capped at 16 MiB including base64. Input reads snapshot a
regular file once and have a 30-second lifetime including open/stat; late opens
are closed after cancellation. No path is expanded from JSON/text, no image is
transcoded, and no URL is fetched as input. HTTPS inputs pass through only under
the SDK's declared input contract; local files are encoded inline. A new private output directory
must have an existing parent. Before opening keys or account custody, a probe
exercises the same exclusive write/fsync/hard-link publication used for results.
Saving checks the reserved directory's identity, writes private temporary
files and atomically links them under fixed numbered names without replacing
an existing destination. Only known MIME types select an extension; other
content uses
.bin. A final receipt projects model/provider/binding, sizes, hashes and local paths, never prompts, tokens or provider metadata. A failed save reports already published artifact paths without restarting generation. Cleanup removes only owned temporary files and a still-empty reservation, never recursively deletes an output directory. - Safe completion and presentation. Process signals abort pending media work and are checked before submission. Once the SDK returns bytes, saving finishes even after a signal; cancellation cannot undo upstream charges. Failure output contains classified safe values, including partial-save metadata, with no arbitrary exception, response body or stack. Human-readable paths and metadata have terminal controls escaped. Credentials and GG authority remain invocation-owned and are dropped on completion; the binary uses exit codes without forcing exit through a pending custody or file write.
- Explicit credential checks before registration. CLI
ai providers configurevalidates the entered key through the shared AI owner, then invokes that owner's single authenticated GET before opening custody. The host permits only OpenRouter's/api/v1/key, Vercel AI Gateway's/v1/credits, fal's/v1/models/pricingwith exactly one fixedendpoint_id=fal-ai/flux/dev, and Tripo's/v3/account/balance. This does not grant other platform APIs. The shared owner rejects redirects, bounds the request/body lifecycle to ten seconds and 64 KiB of UTF-8 JSON, and discards account/key/pricing metadata. Rejected, denied, malformed, cancelled or unavailable checks never replace the stored key. ElevenLabs has no suitable permission-neutral check and reportsnot_supportedwithout a request. Acceptance is transient metadata; it is neither stored nor consulted as future authorization. Ordinary reads and generation never invoke checks. Future custom endpoints require their own credential/destination policy. - Launcher scope. The npm launcher holds no credential. It hands
fxand the arguments after it unchanged to the exactly pinned@grida/fx, a separate product with its own key loader; FX receives no CLI credential, custody path or GG grant. Its update check is one credential-free GET of npm's publicgridadist-tags, at most daily, from a detached process with an empty environment. It sends no identifier, writes only its own record under the Grida home, and never changes a command's input, output or exit status.
Limits and verification. The executable, SDK dependencies, runtime, OS trust store, process environment and same-user code are trusted. This is not an OS sandbox or protection from same-user malware, hostile filesystem replacement, credential-bearing shell history supplied outside the CLI, or memory inspection. Dropping credential references does not guarantee erasure of every temporary allocation or a parent process's environment. The hard-link probe proves that publication works at preflight time, not future disk capacity, crash durability or uninterrupted filesystem access. Signals, local cleanup and no-resubmission do not cancel an accepted provider job or recall a spent/accepted GG grant. Provider-internal execution retries are outside this host's control. Hosted OAuth/GG registration, real provider availability, proxy compatibility and platform release certification remain separate gates. Synthetic socket/installed-package checks do not prove those services or replace GRIDA-SEC-011's real local OAuth proof.
Files bound by this id.
- npm launcher, update notice
and launcher tests — executable selection, the
fxhandoff to the pinned@grida/fx, and the credential-free update check. - Native CLI grammar, safe failure types, entry and output — syntax and output gates before host work. The conformance runner, golden cases and native parser driver exercise these gates with isolated homes, explicit child environments and mutation assertions. Input lowering, file grants/publication, credential selection, domain errors and runtime retain preflight, explicit authority and paid-result publication.
- Rust HTTP adapter, bounded framing guard and transport tests: one admitted connection, all-address DNS validation, original-name TLS, no proxy/pool/retry, credential-free redirects and owned bounded response bytes. A strict 32 KiB guard checks response heads/trailers before Hyper receives terminating bytes; Hyper's buffer-size option alone is not the enforcing boundary. Account JSON is capped at 65,536 bytes with a 15-second deadline; logout and non-success bodies are discarded at headers. The exact Vercel video route closes after its first complete SSE data event using the shared incremental framer, so an open upstream socket cannot withhold an already delivered result.
- Provider credential owner and tests — scoped process inputs, safe presence metadata and invocation cleanup.
- Provider registration and storage adoption tests — one explicit supported check before custody, with no overwrite on failure. The shared provider policy and producer tests retain GRIDA-SEC-004; shared custody retains GRIDA-SEC-014.
- Media composition and tests — public SDK parsing, preflight, authority selection and safe completion; also GRIDA-SEC-006.
- Media transport and tests — fixed credential routes, DNS pinning, TLS authority, credential-free redirects and bounded streams. Hosted GG authority reuses the public CLI registration, whose metadata remains governed by GRIDA-SEC-010.
- The GG chat stream and transport tests reuse direct native admission and hold one connection until completion, cancellation, or drop.
- Input/artifact owner and tests — explicit input, publication preflight, no overwrite and partial-save reporting.
- Request input assembly and tests — explicit file flags, schema-typed scalar input, bounded encoding, advertised variant selection, human inspection and the shared SDK validation boundary.
- Output projection and tests, launcher, and contributor contract — safe presentation and the portable Rust SDK boundary. These retain GRIDA-SEC-010 for account commands.
- Documentation checker and feature-only validation driver — production grammar/input validation without host construction, credential access, output reservation or command dispatch. Installed help/schema checks use empty homes and the platform OS network-denial perimeter.
- Installed native proof and proof contract — separate native processes, private homes and synthetic local OAuth/account/GG endpoints, including preflight, bearer separation, artifact publication and cancellation. No real provider call is made. The obsolete TypeScript media proof and Node CLI preloads were removed because they could not instrument this executable; native egress enforcement is exercised by the HTTP adapter tests above.
The CLI rigging entry and its boundary tests are
command runtime and
installed acceptance proof.
They consume the neutral rigging SDK with explicit CLI file grants and a chosen
BYOK or GG funding source. GG requires explicit organization selection and the
existing native account exchange into invocation-only scoped authority; it never
inspects BYOK keys or falls back to them. ai rigging check returns structured
eligibility; ai rigging run is the explicit paid submission and publishes GLB bytes through the existing safe
output directory. --mesh snapshots one regular file under the SDK's
60,000,000-byte bound; JSON input retains its 16 MiB limit. Syntax, mesh/options
and output publication preflight run before key access. Direct Tripo rigging
adds POST /v3/animations/rig-check and /v3/animations/rig;
retargeting and arbitrary query/destination variants remain denied. Rigging
receipts add the feature and safe task ID/reported credits; existing generation
receipts retain their shape. Provider or save failure preserves an accepted
task's identity without retrying it. These files also bind GRIDA-SEC-006 for GG
grant custody and cleanup.
Desktop hook registration,
its tests,
launch profile owner,
native hook owner, and
inspection extension also bind
GRIDA-SEC-004. Desktop hook definitions come only from the global user-owned
$GRIDA_HOME/config.toml; old workspace JSON registries are never loaded or
promoted. Settings-only, main-frame IPC reviews exact configured revisions and
records explicit trust separately from definitions. Source directories may be
user-owned 0755, with no other-writer access or ACLs; private trust receipts are 0600. Registration captures explicitly trusted root/system-owned program bytes,
safe ancestors and literal arguments, while native admission validates the
complete bounded launch profile. Fresh workers load current trusted definitions;
existing workers and accepted work keep their captured policy. Checks run in the task's captured
read scope without networking or credential access. Text-only reviewers gain
no filesystem grant to run checks. Inspection does not execute handlers, and
missing or changed programs do not prevent observational recovery or Stop.
The master lifecycle decides
event order and bounded continuation; it receives no credential authority.
The chat selection owner, bounded raster preparation, and Main draft/default coordinator with its tests also bind GRIDA-SEC-004. Selection files contain opaque connection/model preferences, never credentials or grants, and inherit the native/Desktop data-root tool denials. Preparing an attached image does not broaden those denials or the separate generation-reference transfer contract. Existing account/provider custody and captured dispatch authority remain unchanged.
What it protects. Independent native applications share BYOK API keys in one private plaintext TOML authority per Grida home. Account OAuth (GRIDA-SEC-010), ChatGPT subscription OAuth (GRIDA-SEC-008) and memory-only GG grants (GRIDA-SEC-006) remain separate. A provider key does not establish Grida identity.
Vulnerable scenario (prevented). Independent writers lose one another's keys, unsafe file aliases expose credentials, corrupt storage silently selects a stale copy, or a deleted key reappears when an old mixed credential file is imported. A partial migration could retire its source before the canonical replacement is durable or discard unrelated OAuth records.
How the code prevents it.
-
One explicit authority.
ProviderCredentialStorerequires a normalized absolute native home and uses onlyproviders/credentials.tomlbeneath it. It has no account, project, environment, network, keyring or alternative-file discovery. The separate Node entry leaves the neutral account export unchanged. Its versioned language-neutral protocol defines strict TOML types, UTF-8, provider/key/file bounds, no unknown fields and fixed safe failure codes. Missing files alone mean absence; malformed or unsupported files are errors. Listing reveals IDs only; secret reads are for trusted native SDK injection. -
Private publication. The existing private-file owner validates every path component, file ownership/mode/link count, opened inode and macOS ACL grants. Existing safe 0755 ancestors are permitted; the provider directory is 0700 and its files 0600. No existing permission repair or unsafe alias is accepted. Writes create an exclusive private temporary, fsync, rename and sync the parent. Post-rename failure never restores old credentials. Cleanup under lock removes only validated owned temporary names and never adopts them as credentials.
-
Cross-process exclusion. All operations use the same private SQLite rollback lock, including readers and removal of absent keys. A process-wide queue coordinates separately loaded copies before opening/closing its inode. OS locks release on crash; bounded acquisition never steals a live lock. The lock stores no secrets and never rolls back a completed file publication.
CredentialLockexposes that same coordination for another native credential writer without exposing SQLite handles or changing its file protection policy. -
Irreversible migration. A source writer lock precedes the canonical lock. The one-time source callback returns API-key entries only. Existing canonical keys win; absent-key removal leaves a durable tombstone before first import. The merged canonical document and pending fence become durable before source retirement. Pending blocks ordinary stored operations and retries retirement without rereading or importing keys. Complete calls neither source callback. Retirement must preserve unrelated source records and complete durably; its failures remain pending. There is no dual-write mode or fallback to the source.
-
Independent native adoption. Desktop supplies its canonical provider home explicitly, and standalone daemon hosts default to their own isolated data path.
SecretsStoredelegates to the public owner and runs one-time migration through the legacy writer lock. Its routes still expose only presence/set/delete. Linux's retained service binds the same physical provider directory beneath private namespace ancestors with valid mapped ownership. Strict ownership, ACL and path checks remain enabled. The underlying files and SQLite lock inodes are unchanged; migration state and tombstones are neither copied nor reset. Native clients outside the namespace keep the physical canonical home. File/workspace admission excludes both physical private roots and the private namespace prefix; chat-state and preview-profile exclusions also project into bound views. Every updated macOS/Linux OAuth mutation shares the legacy lock and rereads disk before changing a record. Strict legacy reads bypass test environment content; retirement removes API entries only and cleans validated old temporaries. ChatGPT refresh and Grida account login are not migrated into this store. Backend selection precedes access: Windows Desktop keeps its existing host-localauth.json, with no shared-store access, migration, dual writes or failure fallback. Its provider reads reject malformed/blank entries, invalid UTF-8, non-regular or multiply linked files and oversized contents; missing files alone mean absence. Writes reread disk under the existing in-process queue. Provider publication checks the same 1 MiB encoded UTF-8 document limit as reads before replacing a file, so a rejected write leaves custody usable. Provider set/delete preserve OAuth records, and custody failures cannot silently make automatic provider resolution select GG. -
Explicit CLI inputs and writes. The CLI grammar never accepts literal key arguments. Configure reads hidden terminal input or explicitly allocated stdin; input is bounded and validated before custody opens. The terminal is restored on success, failure, timeout or cancellation. Native home resolution reads no project file. Environment/stdin override selection happens before storage is constructed; GG supplies no store capability. Configure/remove await durable mutations through signals. Status and failures project only fixed safe metadata; no key, prefix, parser excerpt or native error is printed. No account setup is required. CLI configuration performs GRIDA-SEC-013's supported provider check before opening custody; ordinary stored-key consumption uses static validation only. The TOML owner itself stays provider-opaque and never performs network I/O. Provider removal leaves account sessions and environment variables untouched.
-
Provider files cannot become tool grants. The daemon supplies the provider directory as a fixed protected native root.
ProtectedRootsrejects ancestor, descendant and alias overlap, including an absent subtree; unresolved/dangling aliases fail closed. File/workspace registries recheck stored handles and roots, so earlier registration cannot retain newly forbidden authority. Agent structured filesystem admission uses the same topology rule before granting reads. Desktop's finite-command policy denies this exact directory while its long-lived credential host retains custody access. Native read-only adapters require a current directory grant and recheck supplied protected roots before opening a target and delivering results. The native permission profile carries the same protected paths into finite command confinement. An approve-once decision remains bounded by those denials. No renderer can configure or remove these protections. The native launch profile is selected by the supervisor and read from a private canonical file. It adds fixed denials for host state, the profile file, and credential homes. File tools also deny installed executables, and confined commands cannot write them. A session working directory only selects an exact matching profile. Chat input and model-editable configuration confer no grants; the approval-gated agent settings file (GRIDA-SEC-004) stays outside every restricted command scope and accepts only reviewed defaults. Explicit Full access relinquishes these command and file-tool exclusions; ordinary-user unconfined code may reach readable credential files and mutate application state. It does not receive keys automatically through the provider bridge. The Desktop launch adapter publishes owner-only profiles from canonical main-selected roots and protects the native state and additional custody paths. The profile path changes with its contents, so simultaneous launches with different selections cannot substitute one another's scope before startup. The native chat store refuses a native chat store that overlaps the selected credential home. -
Credential continuity stays in private custody. The native agent can persist a bounded, versioned record under its explicit private host directory. Each record binds an opaque lineage to a random identity and a salted proof of the credential bytes. It uses the existing native path, ACL, lock, and atomic publication checks. Only the random identity crosses into replay state. A different credential value rotates the identity. Malformed or unsupported custody fails closed. A match establishes equality between the observed values. The host establishes account identity and execution authorization separately. The shared provider store can admit a trusted synchronous action while an exact captured key still matches under its writer lock. It passes no key to the action and rejects reentrant custody access. Errors after the action may have started an external effect and cannot prove that dispatch was refused.
-
Native provider requests keep their selected destination. The HTTP adapter injects a freshly validated credential only for its captured provider binding and finite operation. Responses generation and input counting share that binding and the same configured API base. Counting adds only the fixed
responses/input_tokensroute. It grants no arbitrary URL access or access to a different provider's operation. Stored OpenAI keys require the reviewed vendor base URL, while custom destinations require an explicit environment credential. Requests disable redirects and automatic retries.
Limits and verification. This is plaintext user-level custody, not encryption,
secure erasure, provider revocation, protection from same-user code, or backup
protection. A supported filesystem, OS, runtime and dependencies are trusted.
The shared implementation supports main-thread Node 24+ on macOS/Linux; Windows
and worker threads fail before shared file access. The separate Windows Desktop
compatibility backend requests private file creation but relies on inherited user
directory ACLs: it does not validate Windows DACLs, establish POSIX-mode privacy,
or provide cross-process exclusion. Compatibility with older applications
that ignore the shared locks or keep using the old API-key file is unsupported.
Deleting the whole TOML file or manually changing migration metadata can erase
its fences. A failure after rename may already have committed a complete change.
The source owner is responsible for its format, safe atomic retirement and all
updated legacy writers using the same source lock. CredentialLock preserves a
callback's domain error; its host must project that error safely.
Synthetic private-home tests cover schema/encoding/permissions/aliases, malformed and unsupported stores, canonical precedence and deletion fencing, interrupted retirement and uncertain publication. A copied built package verifies independent processes, mixed ESM/CommonJS copies, restart and SIGKILL recovery. This is local platform evidence, not Windows or cross-platform release certification. Current TypeScript/Rust custody contracts and native installed configuration checks retain the shared-store adoption evidence. The retired TypeScript CLI proof was removed with its obsolete archive/preload assumptions; the current TypeScript custody owner, protocol fixtures and cross-language tests remain.
Files bound by this id.
-
General worker composition and its authority tests — retain the parent's captured permission and provider authority, with private credential roots still denied and no ambient credential source added.
-
Native chat selection, raster preparation, Main draft/default owner, and Main owner tests — product metadata and bounded input preparation inherit fixed private-root denials without changing credentials, replay custody or dispatch authority.
-
Documentation checker and feature-only validation driver — parse configuration examples without opening or mutating provider custody.
-
Native implementation and synthetic cross-language verification: crates/grida-auth/README.md, crates/grida-auth/src/conformance.rs, crates/grida-auth/src/credential_lock.rs, credential continuity store, native agent custody, native provider HTTP dispatch, supervised provider transport, private Desktop broker, Desktop provider selection, Desktop stored-key fixtures, provider broker fixtures, native agent custody tests, native workspace protection, native permission admission, native permission tests, native file adapters, native file opens, file adapter tests, Desktop media registration, media profile protection, confined media read, exact document worker, document isolation tests, standalone file owner, selected document identity receipts, standalone file owner tests, private retained inputs, native retained-input owner, native image input references, native scratch image crop, workspace tests, retained input tests, crates/grida-auth/tests/process.rs, crates/grida-auth/tests/providers.rs, scripts/cli-contracts/auth-driver.mjs, scripts/cli-contracts/auth-process.test.mjs. These preserve this boundary. Rust conformance adapters, where present, are feature-gated and excluded from the distributed executable.
-
Windows credential compatibility tests and provider composition tests — platform-selected host-local custody, preserved OAuth records and keyless GG image resolution, with strict provider failures that never switch the payer to GG. These simulate platform selection with disposable files; they do not certify native Windows ACLs.
-
Native CLI grammar, safe failure types and entry — reject literal-key and conflicting authority syntax before host dispatch. Rust provider store, native files/SQLite lock and auth entry preserve shared TOML custody and migration fencing. The CLI credential resolver, host, runtime and safe errors inspect only selected overrides and verify once before saving.
-
Provider entry, store, store tests, and process tests.
-
Private-file owner and profile lock, shared with GRIDA-SEC-010; existing account guarantees remain enforced.
-
Package contract, build, language-neutral protocol, and conformance fixtures.
-
Daemon credential facade, legacy OAuth owner/migration, migration tests, protected-root owner, alias tests, file/workspace grant tests, file registry, workspace registry, daemon composition, services seam, Node exports, package contract, and daemon contract.
-
CLI provider commands, native home adapter, invocation owner, hidden input, stdin configuration tests, and shared-store adoption tests. Grammar, dispatch, media composition and installed proof retain GRIDA-SEC-013. Shared static/probe policy, producer tests, and the provider entry remain owned by the AI package under GRIDA-SEC-004; they add no provider awareness to the TOML storage protocol.
-
Desktop supervisor, retained-service sandbox, sidecar, composition, outer policy, and native permission loader, with supervisor tests, retained-service sandbox tests, composition tests, outer-policy tests, and native sandbox tests. The built startup proof and its guard distinguish custody-only SQLite access from any other storage startup. These retain GRIDA-SEC-004's channel, sandbox and renderer guarantees. The Desktop contract and agent authority contract document host custody.
-
The media server carries native custody/protected-root facts, never renderer-selected key paths. Built media isolation tests, the agent contract, and the ChatGPT custody contract bind startup isolation and the separate OAuth lifecycle.
What it protects. Composing native account access with media execution does not make the account access or refresh token a provider credential. The CLI host explicitly selects BYOK or a scoped GG handoff, and the corresponding account/GG server verifiers keep their credential families separate. The client authentication blueprint maps this composition alongside browser, Desktop and independent provider sessions.
Vulnerable scenario (prevented). A new media command forwards the user's full account token as an AI key, treats a GG grant as account identity, or turns a missing BYOK key into implicit account access/credit spending. Sharing model operations must not merge the credentials held by their different hosts.
Why it's specifically risky here. CLI and Desktop expose the same models through different account ceremonies and storage owners. A common account, provider interface or HTTP bearer shape does not make those credentials interchangeable. Public application registration/API keys are not user identity.
How the code prevents it.
- Explicit CLI composition. The native command runtime resolves the selected
provider and validates generation input/output admission before account authority.
Its GG branch constructs invocation-owned
ExecutionAuthority::Gatewayinside the auth owner's guarded synchronous grant handoff; no BYOK reader is opened. Its BYOK branch opens provider custody without opening native account custody. Errors do not switch the selected provider or funding path. Completion drops invocation authority; interruption is checked before a subsequent mint or submission. Native agent chat uses the same scoped handoff for explicitly selected GG execution, with its own host-owned conversation state. - Account ingress is not GG ingress. The native bearer owner admits only the configured issuer/client and required user/session/expiry claims, then verifies the same bearer at fixed live OAuth userinfo. Cookies and GG tokens cannot satisfy that account contract. GRIDA-SEC-010/012 own the full native principal and machine request boundary.
- Scoped media authority has its own verifier. GG signs/verifies with its
dedicated server key, HS256 algorithm,
gg:aiaudience, organization and bounded lifetime. The shared mint policy resolves membership before signing. An account bearer cannot substitute for that grant; a resulting GG grant is rejected by the account API. GRIDA-SEC-006 owns cryptographic scope and the Desktop/native mint adapters; GRIDA-SEC-013 owns CLI credential egress. - Existing owners stay independent. GRIDA-SEC-005 owns Desktop account cookies, 010 owns CLI account custody, 008 owns ChatGPT provider OAuth, and 014 owns shared BYOK. The blueprint is an index of those owners, not a new store, token type, authentication service or permission mechanism.
Limits. This is a composition contract over existing enforcement. It does not certify hosted logout, make all clients' logout scope identical, revoke already-issued GG grants immediately, or sandbox an account bearer against every legacy/browser/Supabase endpoint. CLI explicit-provider policy is not an account-wide BYOK-only preference. Independent stores do not prevent deliberate account-wide revocation by another client. Keep release-specific acceptance and incident investigations out of the architectural guarantee.
Files bound by this id.
-
Native implementation and synthetic cross-language verification: crates/grida-cli/src/account_tests.rs. These preserve this boundary. Rust conformance adapters, where present, are feature-gated and excluded from the distributed executable.
-
Rust account composition and runtime acquire a scoped GG grant for the selected organization, independently of provider custody. Account transport and media transport are distinct capabilities; no account token enters media execution.
-
The native agent command receives only the scoped chat connection under the same account handoff.
-
CLI media composition and tests — real SDK handoff, BYOK/account independence, missing-key failure, no stale grant reuse or credential output.
-
CLI rigging composition and tests — eligibility and rigging use the same explicit-organization scoped handoff, never account tokens as provider credentials; also GRIDA-SEC-006/013.
-
Native bearer verifier and tests — accepted account family and live issuer verification, including rejection of other credential classes.
-
GG token policy and tests — separate scoped authority and lifetime.
-
Native GG exchange tests — membership-bound mint and the minted grant's rejection as account authority.
-
Client authentication blueprint — the cross-client authority and lifecycle model contributors must keep aligned.
- Allocate the next sequential id (
GRIDA-SEC-016for the next one). - Add an "Active boundaries" subsection here with the same shape as GRIDA-SEC-001: what it protects, vulnerable scenario, why it's risky here, how the code prevents it, files bound.
- Tag every relevant file with the new id (header comment for source, callout block for docs, comment in scripts).
- The skill at .agents/skills/security/SKILL.md auto-loads on any "GRIDA-SEC" mention; no need to register per-id with the skill.
Please email [email protected] or [email protected]. We respond within 48 hours.
Include the affected route, authentication context and reproduction steps when reporting a routing vulnerability.