דילוג לתוכן
מרכז התיעוד
לאתר LinkNodes Energy
LinkNodesENERGYתיעוד

טוענים את החיפוש…

    חיפוש גם בתוך המאמרים ↑ ↓ לניווט Esc לסגירה

    לאתר החברה

    אבטחה ופרטיות

    טיוטה: שחרור זהות בפיתוח

    תיעוד סביבת Development, מחזור חיי עובדים, בידוד ותנאי קידום.

    בעמוד הזה

    Date: 2026-11-21. Source base: PR #66, 3da77f2be204e973da5c3da1de28a95b62ef57e7.

    Scope#

    Finish the identity foundation in isolated Development before a paid Clerk upgrade or production promotion. This change covers environment isolation, tenant assurance, organization/employee lifecycle, bounded reconciliation and verification. Existing mobile/web layout, map markers, approved assets, provider preferences and commercial offers are preserved. Company-admin work in internal-admin-autonomy.md is architecture only.

    This is a source and Development-configuration release. It is not a signed iPhone release or evidence that production migration, customer SSO, supplier APIs or payments have been activated.

    Verified Clerk Development configuration#

    Application: app_3LnOGGQ5iSA2KlooyXeTeuAHVoB / LinkNodes Energy. Development instance: ins_3LnOGD8pvDUWRSdpldufQF6d7o6.

    Each change was read, schema-checked, dry-run, applied only to Development and read back:

    SettingResult
    Native biometric sign-inEnabled; enrollment remains voluntary
    Authenticator app and backup codesEnabled
    Globally required MFA for every userRemains disabled; tenant policy controls selective enforcement
    OrganizationsEnabled
    Organization membership limitUnlimited in Development
    Forced organization selectionDisabled; Personal accounts remain available
    Session token claimsExisting role: authenticated retained; lne_session_created_at: {{session.created_at}} added
    Session token lifetime / clock skewUnchanged: 60 / 5 seconds
    Google / AppleExisting Google preserved; Apple remains unactivated pending verified Apple registration

    Enabling Organizations initially changed Clerk's default to require organization selection. This was explicitly reset and verified false before completion. No production configuration, subscription, DNS, signing identity or customer account was changed.

    Clerk documents the immutable session-creation shortcode in its JWT shortcode reference. A refreshed token's iat does not represent a fresh sign-in. The claim configuration has been verified; a genuine signed Development session still needs end-to-end validation once the isolated backend and its credentials exist.

    Environment contract#

    Server#

    The backend explicitly selects LNE_BACKEND_ENV=development|production. NODE_ENV is not an identity boundary. Required values are SUPABASE_PROJECT_REF, CLERK_JWT_ISSUER_DOMAIN, NEXT_PUBLIC_APP_URL, existing Clerk public/server keys and public Supabase URL/key. APP_ORIGIN, if supplied, must match the application origin. Public Clerk key hostname must match the exact issuer; test/live key prefixes must match the selected environment. A Supabase legacy JWT key is checked for its role and project reference. New opaque publishable/secret keys still require a real connection test; structural validation cannot prove their project association.

    platformConfigured, authenticated client/web factories and privileged database creation share this validation. A mismatched environment fails before a database client is used. The web provider is not mounted for an invalid configuration. Verified session claims retain issuer, subject, session ID, factor ages and creation time; a session from another issuer or an incomplete session cannot become an authenticated client context.

    Current Singapore production and the reserved Frankfurt production migration target are both excluded from Development, as are the other observed company projects. Production remains explicitly bound to the existing LinkNodes project references and product origin. Local HTTP requires the explicit local-development override and is unavailable on Vercel.

    Run the configuration check without printing secrets:

    node --experimental-strip-types scripts/identity-environment-preflight.mjs
    

    Native#

    The existing public variables remain required, with these explicit additions:

    EXPO_PUBLIC_APP_ENV=development
    EXPO_PUBLIC_BACKEND_ENV=development
    EXPO_PUBLIC_API_BASE_URL=<isolated HTTPS backend origin>
    EXPO_PUBLIC_WEB_BASE_URL=<same isolated HTTPS origin>
    EXPO_PUBLIC_SUPABASE_PROJECT_REF=<isolated project reference>
    

    Invalid/mixed values block Clerk mounting, token retrieval/API requests, direct Supabase creation and management links. Management links never include a session token. The development-preview EAS profile uses the Development environment and its own channel; it is the physical-device test target. Existing preview remains explicitly production-backed and is not silently redirected.

    EAS pre-install runs the dependency-free release preflight automatically. Supply the new public variables in the selected EAS environment as well as any build-profile overrides: eas update does not automatically inherit a build profile's env block. Native runtime remains 0.2.0; the old installed 0.1.0 build is not compatible with the new native modules.

    Tenant assurance and direct database access#

    The migration adds server-owned policies, revoked session/user registries and a short-lived enterprise-proof boundary in ev1_private. No policy row is enabled by installation. Existing Supabase memberships remain the application-role authority.

    The canonical role_for helper now checks lifecycle and assurance. Existing RLS policies, tenant RPCs and storage authorization therefore share the gate, including direct Supabase requests that bypass Next.js. The registered-vehicle service write rechecks the authenticated tenant context after an external lookup, before its privileged mutation.

    An enabled policy pins the issuer. Mandatory Clerk MFA requires two actual nonnegative signed factor ages, both within the configured freshness window, including elapsed time since token issuance. A missing second factor is not accepted through a helper's fallback to first-factor verification. Maximum session lifetime uses lne_session_created_at; token refresh cannot extend it. Pending tasks, revoked sessions/users and impersonation under an enabled policy are denied.

    Exact SSO limit#

    The installed Clerk Backend Session API does not provide the verified current-session enterprise connection required by our stricter tenant policy. Active organization, email domain, a linked SSO account or client-reported success are insufficient substitutes. Consequently, required SSO denies access until a trusted provider adapter supplies a real session-bound assertion. The proof is scoped to tenant, Clerk organization, issuer, user, session, connection and policy revision and expires within five minutes. No public route can create it; no proof writer has been activated.

    This prevents a false claim of completed SSO enforcement. Customer IdP integration must establish that evidence path and its revocation behavior before enabling require_sso. Clerk delegates MFA to the IdP for ordinary enterprise SSO; an IdP's MFA assertion must not be confused with two Clerk fva entries. Keep the strict Clerk-MFA policy disabled for a customer SSO tenant until the chosen IdP assurance design has been verified.

    Official references: session token claims, organization SSO, SSO and bypass behavior.

    Employee lifecycle#

    The new webhook accepts raw signed Clerk events only after the SDK signature/timestamp check and exact instance binding. Payload size is bounded; unverified JSON cannot mutate membership. Environment-specific provider binding and tenant sync settings are separately enabled on the server.

    Provisioning uses the exact trusted ev1_tenants.clerk_org_id mapping and an explicit provider-role mapping. Provider administrators do not automatically become application owners. Existing manual roles stay under application control; managed memberships may be synchronized within the configured role policy.

    Event receipts, ordering/version checks, deletion tombstones and transactional operations prevent duplicate deliveries or delayed updates from restoring removed access. Offboarding suspends app memberships, linked drivers and our credential records. A provider's physical RFID/card cannot be considered revoked until that provider's integration acknowledges it. Tenant-only removal does not revoke a user's other tenants. Global user revocation is separately recorded and schedules bounded session revocation.

    The internal worker uses a dedicated bearer secret, short leases, bounded batches/retries and an outbox. Reconciliation checks an exact organization/user pair, not absence from a partial page. An application member who was invited through the existing product and has never been linked to a verified Clerk membership is preserved on an empty lookup; absence cannot silently switch membership authority. A separate last-check ledger makes these scans fair without fabricating provider linkage. A new membership after removal receives the newly mapped role, never a stale privileged role.

    Audit evidence contains identifiers and outcomes, not raw provider bodies, email addresses, tokens or recovery codes. Export is bounded and restricted to the tenant's owner/admin through the same assurance and role gate. These endpoints require a real configured webhook and scheduler before they become live automation.

    Deployment order#

    1. Provision a dedicated Development database/branch with no production data. Inventory on this date found no existing development branch; Singapore and Frankfurt are production resources and were not repurposed.
    2. Apply all source migrations and unified-energy extensions to that isolated database. Configure native Supabase third-party trust for only the Clerk Development issuer. Never add the development issuer to a production project.
    3. Inject a Development Clerk server key and matching database credentials through server secret storage. Set the explicit environment variables. Create a dedicated signed Clerk webhook to the Development endpoint and bind its instance/issuer in the database. Webhook registration and a server secret are not currently present in the inspected Vercel project.
    4. Enable sync for two synthetic test organizations with explicit role maps. Configure a scheduler for the bounded worker. Run real-user positive and negative tests: wrong organization, missing MFA, stale session, offboarding, repeated/reordered events and direct database access.
    5. Build development-preview after Apple App ID Prefix/team, entitlements, device and signing credentials are confirmed. EAS authentication to [account-redacted] is already resolved; previous credential inspection found no iOS credentials/builds. The enrollment reference is not an App ID Prefix.
    6. Complete physical iPhone Face ID/Apple/SSO checks. Only then consider the paid Clerk plan, production credentials/trust and a separately reviewed cutover. A plan upgrade does not replace those integration checks.

    Hosted GitHub Actions was previously blocked before any test steps by account billing/spending restrictions. Local evidence is not a hosted CI pass; rerun the exact release commit after the account issue is resolved. Do not deploy an unverified or mismatched identity configuration to compensate for that block.

    Verification record#

    Final local verification passes 741 server/web unit tests, 295 mobile tests, 309 executable PostgreSQL checks, and four provider-alias tests. The database run applies all 20 source migrations plus the unified-energy extensions, runs the full billing/tenant/vehicle/invitation/identity/energy suites and verifies that every customer fixture is cleaned up. The new identity portion contains 33 assurance and 32 lifecycle database checks. Fourteen webhook endpoint tests use the actual installed Clerk signature verifier. Root/mobile TypeScript, scoped ESLint and the optimized Next.js production build pass.

    The live-energy verifier's trigger allowlist was extended only for the reviewed identity_respect_manual_suspension row-update trigger. Its effect is a transactional private-ledger write; the guard still rejects other unexpected triggers. Tests use isolated local PostgreSQL 17, never a hosted production database. Actual provider login, webhook delivery, iOS signing and customer IdP assurance remain external acceptance gates.

    iOS and Android JavaScript exports also pass from this source. They validate bundling, not native signing, device installation or biometric hardware behavior. The first Next.js build attempt could not resolve dependencies through the scratch snapshot's external symlink; materializing the same unchanged dependency files inside the isolated stage resolved it, and the normal Turbopack production build passed without changing project configuration or dependency versions.

    Rollback for source is the parent PR #66; rollback for the installed app remains the existing runtime 0.1.0 preview. New DB policies default off. Disabling sync intentionally does not undo an offboarding tombstone; restoring an employee requires a deliberate verified lifecycle operation. Never delete audit evidence or remove revocation protections to recover a login.