CIP-37: Sign in with Cowboy

​

1. Background

​

2. Goal

• Every actor website starts with Only me access, including sites without a routes table, static sites, and workload sites.
• The owner can view a site after Continue with Cowboy or Continue with Google, when that Google identity is explicitly linked to the owning Cowboy account.
• Continue with Cowboy on a hosted website verifies a wallet proof directly at the gateway. With a working gateway and chain, Dashboard or provider failure does not prevent a new wallet login or invalidate an existing gateway-direct wallet session.
• Private pages load directly in the browser once the gateway admits the signed-in owner. The gateway’s login page shows who is signed in and offers sign-out. Only the owner can change sharing, through a wallet-approved transaction.
• The gateway rejects an unauthorized request before actor execution, storage fetch, payment admission, or actor-funded job dispatch.
• Third-party websites and native apps use the same identity service through OpenID Connect (OIDC).
• Cowchat Mac can authenticate an account and obtain a separately authorized room-discovery grant. Implementing that client is outside this CIP’s implementation slice.

​

3. Scope

​

4. Identity

​

4.1 Authentication authorities and principal

{"chain_id":"1863","chain_instance_id":"0x<64 lowercase hex digits>","account_address":"0x<40 lowercase hex digits>"}

​

4.2 Wallet authentication

EIP712Domain(string name,string version,uint256 chainId,bytes32 salt)
  name = "Cowboy Login"
  version = "2"
  chainId = <configured chain_id>
  salt = <configured chain_instance_id>

Login(address account,uint64 policyRevision,string issuer,bytes32 challenge,bytes32 transactionId,string purpose,bytes32 binding,uint64 issuedAt,uint64 expiresAt)

​

4.3 Google linking

​

4.4 Credential tiers

​

5. Common sign-in protocol

​

5.1 OIDC surface

​

5.2 Grants

​

5.3 Hosted websites

​

5.3.1 Gateway-direct wallet login

Issuer and site origins

• the flow cookie __Host-cowboy-login-<transactionId hex> holds a random browser secret for one sign-in attempt and lasts 180 seconds; the database stores only its hash, and completion requires it;
• the session cookie __Host-cowboy-session holds the random session token; the database stores only its hash, and its Max-Age is AUTH_SESSION_TTL_SECS.

1. At most one Host header, naming a configured site. An unknown host gets 404.
2. Exactly one Origin header, equal to the issuer origin. Anything else gets 403.
3. Exactly one Sec-Fetch-Site header with the value same-site or same-origin. A missing or duplicated header gets 403. A cross-site or none value gets 412 with a setup-required message, because the issuer and site are not laid out on one registrable domain.

Finalized-state proof

• the proof verifies against the trusted checkpoint through the validator set’s finality signatures;
• it contains exactly the requested claims; an omitted account claim fails closed, and an authenticated absence of AccountAuth selects AddressDerived;
• the ActorOwner record is present and names the target actor;
• the finalized block’s timestamp is at most LOGIN_PROOF_MAX_AGE_SECS (60 s) old and at most LOGIN_PROOF_CLOCK_SKEW_SECS (3 s) ahead of the gateway database clock.

​

5.3.2 Optional provider login

​

5.4 Expiry and logout

• adding a key to the account’s policy;
• raising or lowering the threshold;
• any other change that advances the policy revision but keeps every key that signed the session.

​

6. Native clients and Cowchat

​

7. Website access

​

7.1 Site policy

WebAccess {
  version: 1,
  actor: bytes20,
  revision: u64,
  owner_at_update: bytes20,
  visibility: Owner | Public,
  published_routes_digest: bytes32 | null
}

​

7.1.1 Actor ownership

ActorOwner {
  version: 1,
  actor: bytes20,
  revision: u64,
  owner: bytes20
}

​

7.2 Route policy

Access = "site" | "owner" | "public"

​

7.3 Freshness

​

8. Private site pages

​

9. Enforcement

1. Handle reserved authentication, health, and protocol endpoints. Reserved data-bearing endpoints are not automatically public (§10).
2. Resolve the exact host/actor binding and current proof-backed policies.
3. Resolve the route, or the Site no-table fallback under the owner-only default. Answer CORS preflights without invoking the target.
4. Read any principal from the gateway session or a validated resource-specific access token. Verify its immutable authentication source, full chain, target binding, expiry and applicable live state. GatewayWallet uses gateway-local session/revocation and current chain policy, without a provider status check. ProviderOidc and provider-issued tokens additionally require verified issuer/audience and live provider session/grant status. An explicitly Public route does not require a principal.
5. Apply the selected route’s Site, Owner or Public rule (§7.2), including the explicit Public exception to a private site gate. Reject callers who fail the applicable rule without fetching application content, running a handler, reserving actor funds, or submitting a job.
6. Apply origin/CSRF, payment, independent account signatures, and target-specific checks. Dispatch only after all required checks pass.

• its Origin header is exactly the site origin;
• it has no Origin, is a GET or HEAD without an upgrade, and is a top-level document navigation (Sec-Fetch-Mode: navigate, Sec-Fetch-Dest: document), or a same-origin request (Sec-Fetch-Site: same-origin).

​

10. Bypasses and receipts

​

11. Confidentiality and abuse

​

12. Launch contract

​

13. Parameters

​

14. Acceptance

• A newly deployed site is discovered through the explorer before its owner first visits. Anonymous and unrelated signed-in callers cannot read private application content, invoke a handler, submit jobs, or charge the actor. No-table, rejected non-final schemas, static, workload, custom-domain, deep-link, HEAD, POST, WS, SSE, asset, and receipt paths are covered.
• The owner enters through Cowboy or an explicitly linked Google account and sees the same principal on the login page. An unrelated Google account, matching email, reassigned Workspace email, hd hint, or same-domain employee cannot become the owner. Link replay, linking to another account, unlink revocation, and account switching fail safely.
• With chain and gateway services healthy, disable Dashboard, the OIDC provider and access to their account/session/status APIs. A new direct wallet login still succeeds; an existing GatewayWallet session and its pages and subresources continue beyond AUTH_STATUS_MAX_AGE_SECS. No provider subject/account row or discovery/JWKS/status call is made. Provider-derived sessions fail closed at their status bound and a fresh direct wallet proof can establish an independent local session. Re-enabling the provider cannot relabel, replace or revoke that local source. Chain-policy/ownership changes, local logout/revocation, expiry and an unavailable gateway-local store still deny access or close streams as required.
• Direct wallet vectors bind the exact configured gateway authentication origin, complete chain, selected account, actor/site resource and fixed client/scope context. A provider proof, link-management purpose, wrong host/actor, stale target binding, replayed challenge, missing or foreign flow cookie, wrong Origin, cross-site Sec-Fetch-Site, issuer equal to a site origin, or client-selected authentication-source label cannot establish a direct session. Browser tests cover cross-tab completion, login CSRF, session fixation, the cookie attributes and clickjacking refusal; multi-gateway tests prove at most one completion per challenge. Every issued statement fits its complete verification envelope before persistence.
• Login vectors verify against the account’s current CIP-49 policy: exactly-threshold 2-of-3 accepts and one or three slots reject; a high-S slot, an out-of-range or descending index, and a signature at a stale policy revision reject; an account’s original address-derived key rejects after the account replaces it. A policy change between challenge and completion makes completion fail.
• Proof tests cover a proof older than 60 seconds, a proof more than 3 seconds in the future, a proof missing the account or ActorOwner claim, an ActorOwner for another actor, and a proof that fails checkpoint verification; each rejects login and session recheck.
• Key-change tests: adding a key and changing the threshold keep every session; removing a key ends exactly the sessions it signed on the first request after the recheck interval, while sessions signed by other keys continue. When the RPC is unavailable at a due recheck, the request is denied and idle time does not advance.
• Sign out everywhere succeeds with the RPC unavailable, ends every session for the account on every replica sharing the database, and refuses challenges and completions begun before it. A fresh wallet approval afterwards establishes a new session.
• Session tests cover the initial idle deadline, accepted foreground and background requests renewing idle time only up to the fixed absolute deadline, and rejection at either deadline before renewal. Tests include page polling, assets, refresh/status/keepalive requests, open streams and their periodic authorization checks keeping an idle session alive. Dependent streams close when the session expires; session activity never renews native unlock or Confirm.
• Actor code can change or forge its application __OWNER__ value without changing the protocol actor owner or gaining publication authority. Direct and actor/deferred deployment, genesis configuration and forks establish the specified owner; forks never inherit site publication. Explicit Public routes remain public until the owner changes them. Ownership transfer requires the current owner’s direct signature and both revisions, clears publication atomically, and rejects stale approval replay even after ownership returns to the original account. Actor writes, deletes and checkpoint/fork-copy attempts cannot forge ownership/access metadata.
• The owner explicitly publishes an unmodified generated template and a no-table site; an anonymous visitor can load their page and assets, while explicitly owner-only API routes stay private. Route changes invalidate previous public approval until re-approved. Then locking rejects new Site-gated requests after finalization; explicitly Public routes retain their declared access. Old public cache entries, alternate gateways, direct backends, open streams, and captured receipt URLs do not bypass the lock. Stale or unavailable policy and applicable source-specific status reads fail closed.
• Actor HTML, scripts, service workers, forged context headers and sibling actor CSRF cannot read the session cookie, set reserved cookies or change site access. Private-site responses carry frame-ancestors 'none', and cross-origin framing attempts fail. Real-browser tests cover session cookies, the redirect to sign-in and back through Continue, and subresources, including Safari. A custom domain outside the issuer’s registrable domain gets only the setup-required response.
• A third-party OIDC client signs in without receiving Store, spending, room access, or an Unlocked/Confirm credential. Reused login, linked Google, code exchange, refresh, and session activity never create or extend unlock; passkey assurance requires a verified ceremony and Confirm retains its exact signed-request check. Authorization, consent, login, and linking pages reject cross-origin framing in real browser tests. Parallel refreshes and reuse revoke the whole family/grant and invalidate its access tokens within the status bound; absolute/idle expiry, the first refresh after the initial idle deadline, and lost-response reauthorization are covered. Wrong issuer, audience, account chain, nonce, redirect, PKCE verifier, expired token, replayed code, token confusion, and signing-key rotation have positive and negative vectors. The implementation uses existing reviewed OIDC libraries rather than bespoke token validation.
• A native test client using Cowchat’s registered profile signs in through the system browser and obtains only its room-discovery resource grant. The service returns authorized rooms, rejects another account’s/private-room probes, and revokes discovery and live subscription access. Sign-out and account/chain switching remove local room state. This can be exercised with a protocol test client before Mac UI work lands.
• On a private site, anonymous GET of a declared Public asset succeeds, and anonymous POST to a Public webhook reaches the actor. Site and Owner routes remain protected. A Public wildcard cannot expose a protected object through a trailing slash, an index name, a mount alias or an SPA fallback. Reserved projections remain protected, and percent-encoded explicit actor identifiers cannot bypass admission.
• Protocol vectors encode the final route schema and reject missing access fields and unsupported versions before first host exposure. They bind owner-approved sharing revisions. Actor code, a Google session, and a stale owner cannot publish. Ownership transfer invalidates the previous publication. An operator-only static route cannot become public through an absent-table approval. Concurrent lock/public updates reject stale revisions rather than overwrite one another.

​

15. References

• OpenID Connect Core
• OAuth token introspection, RFC 7662
• OAuth token revocation, RFC 7009
• OAuth protected resource metadata, RFC 9728
• OAuth security best current practice, RFC 9700
• OAuth for native apps, RFC 8252
• OpenID Connect back-channel logout
• Google OpenID Connect