Copy to Dock Pilot

The full Helm Pass connector details, ready to paste into your Dock Pilot chat. Nothing shortened or left out.
Copies the complete instructions in one tap, including everything below. Then open your Dock Pilot chat and paste into its message box.
Download full instructions (.txt)
Full Dock Pilot implementation instructions
Build the Dock Pilot half of the full Navi Wake Helm Pass member benefit.

Navi Wake is a separate app. Its receiving side is implemented; do not copy or rebuild its maps, paid features, Stripe checkout, or authentication inside Dock Pilot. Eligible active Boat Club members should tap Maps in their Dock Pilot member app and land in Navi Wake with the FULL Helm Pass included, without a second purchase or a second login when their Dock Pilot session is current.

SCOPE AND SAFETY
- Work in the existing Dock Pilot project. Inspect its real member authentication, business/tenant boundaries, active membership and household/primary-account eligibility helpers first.
- The principal is the current MEMBER session, not a staff/admin session and not an email/member ID from a request. Never turn a staff login, rental reservation, monitor session, inactive membership, or arbitrary query parameter into a member benefit.
- All eligible active club membership levels get the full pass; do not reinstate migration-review/sign-off gates previously removed by the owner. Keep existing expiry, selected/primary-member, business and eligibility checks.
- Add this connector and the existing member Maps link only. Keep booking, billing, saved member data, navigation structure and staff permissions unchanged. No charge, subscription, member import, or live test-member change is needed.
- Use the project's real database integration for grants. Rehearse additive schema in isolation and obtain the required approval before live schema changes. No localStorage, in-memory-only production grants, shared coupon, client-side premium flag, trusted-email shortcut, or mock auth.

NAVIGATION
Make the member app's Maps entry a top-level external navigation to:
https://www.naviwake.com/partners/dock-pilot/launch?lake=lake-norman-nc
Do not prefetch that launch URL and do not iframe Navi Wake. Do not append email, member ID, membership status, access tokens or refresh tokens. Navi Wake initiates a fresh OAuth authorization every launch, including when its browser already has another person's Navi Wake session.

PROTOCOL: OAUTH 2 AUTHORIZATION CODE + PKCE S256
Public client ID: naviwake
Issuer: https://www.dockpilotsoftware.com
Scopes: profile email helm_pass
Token endpoint authentication: none (PKCE and the exact registered redirect URI are mandatory, not optional). No shared secret or new API key needs to be pasted into Navi Wake.

Register exactly these production callback URIs:
https://www.naviwake.com/api/auth/oauth2/callback/dockpilot
https://naviwake.com/api/auth/oauth2/callback/dockpilot
Do not use wildcard preview callbacks. Test with an isolated provider/client; if a preview callback is needed, explicitly register only that exact controlled preview origin and keep it out of the production allowlist.

IMPLEMENT THESE DOCK PILOT ENDPOINTS

1. GET /api/integrations/naviwake/.well-known
Return HTTP 200 application/json only after the connector and required storage are ready:
{
  "schema_version": 1,
  "issuer": "https://www.dockpilotsoftware.com",
  "client_id": "naviwake",
  "authorization_endpoint": "https://www.dockpilotsoftware.com/api/integrations/naviwake/authorize",
  "token_endpoint": "https://www.dockpilotsoftware.com/api/integrations/naviwake/token",
  "userinfo_endpoint": "https://www.dockpilotsoftware.com/api/integrations/naviwake/userinfo",
  "response_types_supported": [
    "code"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ],
  "code_challenge_methods_supported": [
    "S256"
  ]
}
Navi Wake checks these exact pinned values. Metadata never selects a different trusted host or endpoint.

2. GET /api/integrations/naviwake/authorize
Accept response_type=code, client_id=naviwake, exact registered redirect_uri, state, code_challenge, code_challenge_method=S256, and the allowed scopes. Validate sizes, characters, scopes and the exact redirect BEFORE using it. Reject plain/missing PKCE. Never redirect to an unregistered URI, including on errors.
Authenticate with the existing Dock Pilot MEMBER session. If signed out, preserve the full validated authorization request through the existing member login using server-side opaque state; no open redirect. Show a clear first-use consent screen for sharing name, email and membership eligibility with Navi Wake. Returning previously approved members with a current session can continue without another password. Recheck eligibility immediately before authorization.
Issue a cryptographically random, single-use code (at least 32 random bytes), store only its hash, and bind it to the exact business ID, actual member ID, client ID, redirect URI, S256 challenge, scopes and authorization grant. Expire it in 60 seconds.
Return a redirect to the registered callback with code, the ORIGINAL state, and iss=https://www.dockpilotsoftware.com. Use Referrer-Policy: no-referrer, Cache-Control: private, no-store. Never put an access/refresh token in a URL.
For a validated request rejected by the member/eligibility check, return error=access_denied, original state, and iss to the registered callback. Do not leak member details in the error.

3. POST /api/integrations/naviwake/token
Accept application/x-www-form-urlencoded.
Authorization exchange body: grant_type=authorization_code, client_id=naviwake, code, redirect_uri, code_verifier.
Atomically verify and consume the stored code with a transaction/row lock or equivalent guarded mutation. Verify exact client, redirect, 60-second expiry, original business/member identity, and SHA256-base64url(code_verifier) == stored S256 challenge. Check current eligibility again. The code can mint tokens only once; invalid, expired, consumed, cross-client or wrong-verifier requests return OAuth invalid_grant without granting access.
Return HTTP 200 application/json with:
{
  "access_token": "opaque cryptographically random token, at least 32 characters",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "opaque cryptographically random refresh token, at least 32 characters",
  "refresh_token_expires_in": 604800,
  "scope": "profile email helm_pass"
}
Store only hashes of opaque bearer credentials in grant storage. Scope every grant to the exact business/member/client. Access tokens must be short-lived (Navi Wake accepts at most 3600 seconds); refresh grants must have a fixed bounded expiry (at most 30 days; 7 days recommended).
Also implement grant_type=refresh_token with refresh_token and client_id. Recheck membership and grant revocation; rotate refresh credentials, preserve family identity, and protect against replay. Concurrent legitimate refreshes from the same grant must not revoke a member accidentally: use a short, bounded same-grant retry window returning the identical securely stored/encrypted replacement response or an equivalent race-safe strategy. Never extend refresh access indefinitely or accept unrelated clients. Return expires_in and refresh_token_expires_in on refresh as well.
No token endpoint redirects. All token responses/errors are no-store; never log codes, cookies, verifiers, tokens or token bodies. Apply the project's persisted rate-limiting and abuse controls.

4. GET /api/integrations/naviwake/userinfo
Require Authorization: Bearer <access_token>. Resolve the hashed grant, enforce token expiry, client audience and revocation, then read the CURRENT source member/primary-account status and expiry from the database. Never accept a browser-supplied user ID as authority. Return 401 for expired/revoked tokens, and no membership data for invalid tokens.
A valid token for a membership that has since become inactive may return the profile below with helm_pass=false and the actual inactive status; it must never keep returning an active snapshot from token-issuance time. A missing/deleted membership must not grant access.
Return HTTP 200 application/json, Cache-Control: private, no-store. Exact v1 shape (values here illustrate the schema, never hardcode a member):
{
  "schema_version": 1,
  "issuer": "https://www.dockpilotsoftware.com",
  "audience": "naviwake",
  "sub": "dockpilot:<business_id>:<member_id>",
  "name": "actual member display name",
  "email": "actual-member@example.com",
  "email_verified": false,
  "membership": {
    "business_id": 123,
    "member_id": 456,
    "business_name": "actual boat club name",
    "membership_name": "actual complete membership level name",
    "status": "active",
    "helm_pass": true,
    "expires_at": "2027-06-30T23:59:59-04:00"
  }
}
IDs are positive integers; sub MUST equal dockpilot:business_id:member_id and remain stable if a member changes email. Status is one of active/inactive/suspended/expired/cancelled. helm_pass is a boolean from real eligibility, not the presence of a session. expires_at is a timezone-qualified ISO timestamp or null only for genuinely non-expiring membership; interpret source date-only expiry through the club's timezone and existing rules. Do not shorten eligibility to the start of the expiry day. email_verified must reflect real verification evidence; never mark imported emails verified without evidence. Do not include card details, passwords, staff information or other members.

NAVI WAKE BEHAVIOR ALREADY IMPLEMENTED
- Better Auth manages state, PKCE, sessions and encrypted provider tokens using the existing real auth tables. No new Navi Wake entitlement table or permanent free-upgrade flag is needed.
- The standard generic OAuth callback strictly requires the configured issuer. User info is fetched from the fixed HTTPS endpoint, never trusted from an unsigned token or URL.
- Existing Navi Wake accounts are never silently merged by email. A matching-email existing user signs into Navi Wake once and explicitly connects their account. First-time members receive a real Navi Wake account without creating another password. Returning linked members use Dock Pilot sign-in.
- Server-side membership verification grants all five paid features: satellite basemaps, 3D helm navigation, saved multi-stop trips, GPX export and offline lake packs, on ALL charted lakes. Safety features remain free.
- Membership is rechecked on protected server requests, and open maps refresh visible entitlement every minute. Unverifiable/expired/inactive membership never grants a club pass. Previously downloaded offline content cannot be remotely erased; do not promise that.
- Paid and grandfathered access remain independent. No existing Stripe subscription is cancelled/refunded automatically. New purchases are blocked for included members and for uncertain linked memberships until reconnected, avoiding accidental double purchase.
- Connection page: https://www.naviwake.com/partners/dock-pilot
- After callback: /partners/dock-pilot/complete verifies current membership before routing to the requested valid lake (Lake Norman by default).

REQUIRED VERIFICATION BEFORE CALLING THE DOCK PILOT SIDE COMPLETE
Use isolated data and fake credentials, not live customer mutations or charges. Cover active member -> Maps -> new/returning Navi Wake session -> all full-pass gates; inactive and expired members; primary/household and cross-business boundaries; staff-only session denied; one-time code replay; wrong verifier/state/issuer/client/redirect; stale and concurrently refreshed grants; source membership deactivation; existing-email linking without account takeover; provider outage fails closed; old paid/grandfathered rights and current member app navigation unchanged. Test actual phone/desktop launch and callback behavior, including sign-out/reload and the explicit-link flow. Report the exact remaining cross-app/deployment validation separately from isolated tests. Do not publish or mutate live customer records without explicit approval.
Connect the apps, not a new subscription
Navi Wake stays separate. These instructions do not change membership records or billing. Both apps still need deployment and real member sign-in verification before launch.