> For the complete documentation index, see [llms.txt](https://nytshift.gitbook.io/nytshift-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://nytshift.gitbook.io/nytshift-docs/implementation-ledger/ns-387-privy-customer-identity.md).

# NS-387 · Privy customer identity foundation

## Outcome

NIGHTSHIFT now has one explicit customer-authentication boundary without conflating a logged-in user, a publicly inspected venue account, a connected wallet or the local execution operator. A configured Privy production app enables Google and EVM-wallet login, provisions an embedded EVM wallet only for users without any wallet, supports linked external wallets, and pins programmatic switching to Robinhood Chain mainnet `4663`. Missing or malformed configuration renders an honest unconfigured state; no demo user or wallet is created.

`GET /api/auth/session` independently verifies the current Privy access token with the server SDK. It accepts the provider's `privy-token` cookie or one bounded same-origin bearer token, rejects malformed and conflicting evidence, verifies the exact app, DID, session and expiry, returns private/no-store data, and suppresses provider error detail. This session grants no operator cookie, trade intent, signer, eligibility, funding, transfer, withdrawal or Agent Pro authority.

## Official evidence reviewed 2026-07-15

* React/Next provider setup and `users-without-wallets`: <https://docs.privy.io/basics/react/setup>
* Custom EVM/default/supported-chain rules: <https://docs.privy.io/basics/react/advanced/configuring-evm-networks>
* External-wallet connection/linking: <https://docs.privy.io/recipes/react/configuring-external-connectors>
* Access-token verification and token handling: <https://docs.privy.io/authentication/user-authentication/access-tokens>
* Exact CSP origins for Privy and WalletConnect: <https://docs.privy.io/security/implementation-guide/content-security-policy>
* Allowed production origins: <https://docs.privy.io/recipes/dashboard/allowed-domains>
* Production HttpOnly-cookie configuration: <https://docs.privy.io/recipes/react/cookies>
* Google OAuth setup: <https://docs.privy.io/authentication/user-authentication/login-methods/oauth>

Pinned packages are `@privy-io/react-auth@3.35.0` and `@privy-io/node@0.26.0`, observed from the public registry on 2026-07-15. Their transitive optional native WebSocket/Keccak build scripts remain denied; the reviewed Reown AppKit version-check script is the only newly approved install script.

## Production activation checklist

1. Create separate development and production Privy apps. Enable only Google and wallet login initially.
2. Add exact origins `https://nytshift.xyz` and `https://www.nytshift.xyz`; do not add public preview-domain wildcards. Use a separate development app for loopback testing.
3. Configure NIGHTSHIFT-owned Google OAuth credentials and reviewed Terms/Privacy URLs before public onboarding.
4. Enable Privy's production HttpOnly cookies, publish and verify the requested DNS record, and retain `SameSite=Strict`.
5. Put the app ID/public client identifiers plus server-only app secret in the private build/service environment. Never put the app secret in source, client variables or local persistent config.
6. Rebuild and restart. `/api/health` must report `identityBrowserState=configured` and `identityServerState=configured` while execution remains disabled and both mainnet flags remain false.
7. Test Google login, wallet login, social-user embedded-wallet creation, wallet-user non-duplication, wallet linking, logout, expiry/refresh, wrong-origin rejection, wrong-chain display and explicit switch to 4663 at 1280px and 390px.

## Deliberately still locked

* Durable profile preferences and the private account workspace are delivered by [`NS-388`](/nytshift-docs/implementation-ledger/ns-388-customer-profile-account-hub.md); complete portfolio aggregation and feature entitlements remain separate milestones.
* Deposits, transfers and withdrawals require reviewed venue/chain routes, exact fee/time/contract previews, simulation, fresh authentication/MFA, user-owned signatures and post-action reconciliation.
* No server signer, delegated signer, smart account, session key, EIP-7702 or ERC-4337 authority is enabled by this milestone.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://nytshift.gitbook.io/nytshift-docs/implementation-ledger/ns-387-privy-customer-identity.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.