Upgrade to the latest published package before reporting a defect that may already be fixed. The npm package and GitHub release page are the public version authorities.

GitHub immutable releases are enabled, and GitHub reports release v0.3.1 as immutable. A repository ruleset also blocks updates and deletion for every v* tag without a bypass actor. The v0.3.1 tag is unsigned.

npm publication uses a protected GitHub environment, an OIDC trusted-publisher binding, and provenance for the package artifact. Verify the package digest and attestation before treating provenance as source identity. The v0.3.1 release run used package commit d17ba544d31beaa33b4955e41c3b3d4e3f141900.

The historical v0.3.0 recovery run checked out package commit 95eb861, while its attestation names recovery commit c23d9df as the workflow identity. GitHub Actions logs expire, so the release notes also record this boundary. Recovery dispatches must run at the release tag. The workflow also requires a successful test.yml run from main for the exact package commit before packaging.

Use GitHub private vulnerability reporting. Do not open a public issue for a suspected vulnerability.

Include the affected version, provider mode, operating system, reproduction steps, and the security boundary that failed. Remove bearer tokens, raw credential files, database URLs, message content, archive data, and disaster-recovery bundles. The maintainer will coordinate disclosure and remediation through the private advisory.

Local mode relies on operating-system account isolation and private file permissions. Anyone who can act as the same operating-system user can generally read or replace that user's Agent Bridge state. Local mode is not a hostile multi-user boundary.

Managed-client mutations may cache a successful native Windows ACL check while one operation lock remains held. The cache is bound to the verified directory identity and is discarded with the lock. New locks, resumed operations, and passive inspection check the ACL again. POSIX permission checks are not cached. A same-user process can still change an ACL on an unchanged object or replace a directory with one that reuses the same filesystem identity. Both actions are within the local-mode trust boundary.

Gateway credentials bind one workspace and principal. The gateway derives remote identity from the credential, applies operation scopes and rate policy, and uses transaction-bound PostgreSQL request authority. Production runtime roles must not be superusers or hold BYPASSRLS. Put every non-loopback gateway behind TLS.

Do not publish PostgreSQL on a public interface. Put it on a private network reachable only by the migration, runtime bootstrap, gateway, backup, and recovery jobs that need it. The checked-in Compose file binds both published ports to loopback and serves plain HTTP for local development. It is not a public deployment template.

Keep the schema-owner, runtime, operator, archive, backup, and restore database authorities separate. Do not copy one client's token or backend file into another client's configuration.

When a gateway receives AGENT_BRIDGE_RUNTIME_DATABASE_CA_BASE64, it decodes the PEM bundle in memory and forces PostgreSQL certificate and hostname verification. The gateway removes sslmode and sslrootcert before it opens the pool. It rejects URL parameters for ssl, a client certificate, client key, or key password. Keep the restricted database URL in a separate secret. Do not put either value in the image, source tree, command arguments, or deployment logs.

Managed PostgreSQL may expose a schema-owner administrator with CREATEROLE instead of true superuser authority. That capability is sufficient for migrations. Native backup requires the schema owner to be a true superuser or hold BYPASSRLS, because the source backup must read tables protected by RLS. A restore target validates a suspended restored schema-owner shell through its own superuser session. Agent Bridge creates internal roles with safe defaults and fails if an existing role has elevated attributes. PostgreSQL 16 and newer may split the schema owner's admin, inherit, and set authority across two catalog rows. Native DR may restore the same authority as one combined bootstrap-superuser row. Security readiness accepts only those documented grant shapes, then checks their effective authority. Registered runtime, control, and archive logins do not receive that exception.

The database-derived backup-reader role is NOLOGIN and has read-only access to Agent Bridge tables and sequences. Only the schema owner may inherit it. The runtime role, control and archive roles, and external principals must not hold it. Native-backup readiness fails on a missing object grant, an added privilege, an unexpected member, or a source schema owner without true-superuser or BYPASSRLS authority. A restricted runtime login cannot validate a suspended restored schema owner.

PostgreSQL native restore does not reactivate external identities. Runtime memberships are omitted. Active control and archive memberships are replaced by explicit revocation events after the restored history. Re-enrollment requires a separate operator action.

Run migrations as a one-shot schema-owner job before starting a new gateway image. Take and verify a native DR backup first. Gateway readiness checks the exact migration plan and protected catalog state. Once a migration changes the database, starting an older image is not a safe rollback. Apply a forward fix or restore the backup into a fresh target and switch authority only after verification.

Drain old gateway instances before migrations 017 and 018. An old image reports /readyz as not ready after the new migration is visible, but a process that was already running can still serve ordinary requests until traffic is removed or it exits. Start the new gateway only after the migration and runtime bootstrap finish.

Migration 018 accepts raw endpoint-migration challenges only as SQL function input. It stores a domain-separated SHA-256 commitment, never the raw challenge, and excludes live challenge rows from native DR data dumps. The challenge proves an active direct credential replacement on one authority. It does not authorize endpoint cutover.

Agent Bridge 0.6.0 removed the direct Supabase runtime adapter. The checked-in v1 schema and migration 006 remain so trusted operators can import historical deployments into the private PostgreSQL schema. Back up the source first, run the migration with schema-owner authority, and move clients to local or gateway mode. The permissive v1 row policies are not a supported runtime security boundary.

Portable archives and native DR bundles may contain message content, routing metadata, credentials, or database state. Their hashes detect changed bytes. They do not encrypt the files or authenticate their source. Store them as private data and transfer them through a separately trusted channel.

PostgreSQL restore executes SQL from the source dump. Use --accept-source-sql-risk only for a bundle from a trusted source. Never activate the source and restored target as authorities at the same time. The restored gateway authority UUID identifies the same logical authority. It does not prevent an operator from activating a live clone, so the deployment cutover remains an operator-controlled safety boundary.

Agent Bridge does not require atrib or another provenance system. A signed wrapper is a separate security and availability boundary. Keep a direct Agent Bridge path available when wrapper health is uncertain.

• Pass gateway tokens through private enrollment or backend files, not shell arguments.
• Keep database URLs in the documented environment variables. Do not put them in CLI arguments, logs, issues, or examples.
• Store Compose password files outside version control with owner-only permissions. Use the deployment platform's secret manager in production. Do not bake passwords or tokens into images, Compose environment blocks, or image layers.
• File-backed Compose secrets retain host ownership on native Linux. The development stack starts a small Node entrypoint as root with DAC_OVERRIDE, SETUID, and SETGID, reads one granted secret, then drops supplementary groups and UID/GID to 1000 before it imports the gateway. The final process has no effective capabilities and cannot regain them under no-new-privileges. The fixed runtime-bootstrap job keeps DAC_OVERRIDE, SETUID, and SETGID while it reads its two secrets, then runs psql as the PostgreSQL account. It rejects runtime passwords shorter than 32 characters.
• Treat client backend files, enrollment files, archives, and DR bundles as secrets.
• Sanitize doctor output and logs before sharing them publicly.

A Docker volume provides persistence, not backup. Keep verified native DR bundles on a separate failure domain with retention and restore drills appropriate to the deployment.