Authentication
Can you prove access?
A provider or credential establishes the way in.
GAMA Identity / Shared platform infrastructure
Different products.
Same person.
One fundamental question.
A shared answer to who is here.
Warm nucleus The person
Aqua pathways The infrastructure
The architecture changes.
The person remains.
01 / Origin
Every app asked the same question.
A list. A memory. A routine. A little shop. Each product has its own world. Underneath, each eventually needs to know who arrived.
Rebuilding accounts, credentials and session handling for every application creates islands. The platform needed a more durable starting point.
01
Another account.
Another session.
The same human.
The foundational problem
Four personalities.
One person outside.
Products should be free to feel different. The person should not have to become a new technical identity every time the product changes.
02 / Experiment
The door can change.
An authentication provider verifies a credential. GAMA resolves that verified relationship to a person inside the platform.
Apple, Google and email/password can be ways in. The principal is the answer that remains after the door has closed.
Identity
Who arrived?
The GAMA principal is the platform’s durable answer.
An interactive architectural example
Choose a door.
Keep the person.
All three methods are explicitly linked to this fictional account. Selecting a door illustrates recognition; it does not sign you in.
Same fictional principal
EXAMPLE-HUMANA verified Apple provider relationship resolves to this example Human.
Selected route: AppleAn unlinked provider is a different case. Email equality alone never establishes this relationship.
Principal / HumanIdentity
Email is not identity.
A provider is not a person.
An email is credential or provider metadata. The current HumanIdentity model has its own identifier and lifecycle.
Returning through an established provider relationship resolves to that Human. Adding a new route requires an explicit link to the authenticated account.
The door can change. The person should not.
03 / System
One shared identity layer.
The current service models a HumanIdentity independently of credentials and sessions. Provider relationships point to that identity. Applications can build on the result.
Recognition, session continuity and permission are distinct responsibilities. Keeping them separate is what makes the whole system understandable.
A readable architecture / Not an operational topology
- 01
Person
One human arrives
- 02
Authentication
Apple · Google · Email
- 03
GAMA Identity
Principal + session
- 04
Product access
Separate permission checks
- 05
Destination
An integrated application
Renewable sessions
Nothing happened.
The session renewed.
The service exchanges valid renewal state for fresh access and rotated renewal state. The principal stays the same.
IdentityKit can restore a locally saved session, validate it with the server, and renew it when appropriate. Restoring local state alone does not prove current validity.
- Sign in
- Establish a session
- Renew within its lifetime
- Continue as the same principal
Expiry and revocation still matter. Continuity is controlled, not permanent.
Shared Apple client / GAMAIdentityKit
A common foundation.
Fewer reinventions.
The Swift actor owns shared authentication behaviour, in-memory state and Keychain session persistence. Validation, renewable access, provider linking and logout have one reusable home.
What the kit owns today
- Registration and login response mapping
- Provider credential exchange and sign-in method management
- Local restore followed by server validation
- Renewal shared across concurrent unauthorised responses, with one retry
- Remote logout followed by local session removal
Applications still choose their integration and account interface. The kit is shared logic; it does not make sessions automatically portable between apps.
Two different questions
Who you are.
What you can use.
IdentityWhich Human is authenticated?
EntitlementDoes that Human have this product access?
The platform evaluates product, membership and entitlement state separately from the Human’s identity. A valid sign-in alone does not grant workforce or platform authority.
Where App Store purchases fit
The inspected Grocery NEXT implementation keeps principal identity, purchase account mapping and transaction environment in separate records. A purchase is evidence for product access; it is not the person’s identity.
This describes the current Grocery NEXT source. It is not a claim that every shipped product has moved to this model.
Real interface / Coco the Llama
The machinery
wears the product’s clothes.
Three sign-in routes. One familiar shop. Recovery is part of the same account experience.
Implementation reality / Reviewed 8 October 2026
A shared direction.
An explicit adoption map.
Coco the LlamaGAMA Identity in the customer website and native Backstage authentication source.Integrated
Grocery NEXTGAMAIdentityKit resolves a validated principal; purchase access remains a separate product concern.Source verified
GroceryMaster / 001The approved app’s inspected authentication source uses Firebase Auth.Existing foundation
Memoir Echoes + TARAThe inspected apps use Apple account / CloudKit continuity for their cloud data.Existing foundation
The four worlds illustrate the reason for GAMA Identity. They do not claim that all four already share one automatic sign-in. Each integration maintains its own session and access boundary.
04 / Problems
The seams matter.
A successful sign-in is only the beginning. Matching emails, expired sessions, changing response contracts and environment boundaries all need explicit answers.
Four failure studies, grounded in current regression tests and documented client fixes. Conceptual scenes show the lesson, not production account data.
Failure 01
The twin
The same email can arrive through different provider subjects. Matching the visible label is not enough to establish that two authenticated identities belong together.
Link a verified method to an authenticated principal. Never merge on email text alone.
Implementation evidence
Service regression tests cover Apple, Google and password-account collisions, plus explicit linking conflicts.
Failure 02
The expired bridge
A login that works now can fail later. An expired access session and a revoked renewal credential are different states, with different paths forward.
Renew valid continuity. Respect expiry and revocation. Preserve retryable network failures.
Implementation evidence
Session tests cover rotation, expiry, revocation and reuse rejection. SDK tests cover shared renewal after concurrent unauthorised responses.
Failure 03
The four passports
A shared service can still drift from its clients. Earlier IdentityKit releases needed fixes for production registration and login response contracts.
Centralise response mapping and test the contract at the shared boundary.
Implementation evidence
IdentityKit 1.0.2 and 1.0.3 document the concrete compatibility fixes. Four passports is the metaphor for duplicated client interpretation.
Failure 04
The wrong environment
A test configuration can look deceptively like a live one. Provider audiences, trusted app destinations and persistence configuration must agree before a flow can be trusted.
Make the environment explicit. Reject incomplete or incompatible configuration.
Implementation evidence
Configuration tests enforce complete provider setup, allowed client identifiers, trusted HTTPS app origins and required database configuration. This is a tested failure boundary, not a claimed production incident.
05 / Solutions
Complexity belongs underneath.
A stable principal. Explicit provider relationships. Renewable sessions. Reusable client behaviour. Product access checked on its own terms.
The infrastructure carries that complexity so the person can get on with the product.
Stable principal
A HumanIdentity exists independently of its credentials and sessions.
Explicit relationships
Verified provider links connect to an authenticated Human; email matching is not a shortcut.
Renewable continuity
Valid renewal state rotates. Expired, invalid and revoked states have explicit outcomes.
Shared client logic
IdentityKit brings common lifecycle behaviour to Apple integrations.
Controlled boundaries
Provider configuration, trusted app destinations and product access remain deliberate.
A product’s own interface
The identity foundation works underneath the app’s personality.
Ordinary human realities
People forget.
Devices change.
The service coordinates email verification and password recovery. Reset challenges are time limited and consumed; replacing a password revokes the Human’s sessions.
A returning device must restore and validate its session, or ask the person to authenticate again. Reinstallation alone is not proof of identity.
Leaving matters, too. IdentityKit logout ends the remote session before clearing local state. Local-only removal is a separate operation.
The emotional north star
Good infrastructure
gets out of the way.
A person returns. A valid session continues. The right access rules apply.
Nothing dramatic happens.
That is the work.
Inside the evidence / What was verified
Implementation
HumanIdentity, federated authentication and linking, session lifecycle, email recovery, PostgreSQL adapters, provider configuration and the current IdentityKit source.
Regression coverage
40 selected service tests passed during this specimen audit: provider identity collisions, explicit links, session rotation and configuration boundaries. SDK renewal and contract tests were inspected separately.
Public evidence
Two unmodified-content captures from Coco’s live public account interface. They demonstrate available screens, not a completed authenticated session or a cross-product login.
Publication boundary
Conceptual routes and the interactive account are illustrative. No private identifiers, credentials, tokens or database records are shown. Source and artwork provenance accompany this specimen.
06 / Evolution
From a login screen to a platform primitive.
Seven architectural mutations describe the direction of the system. These are conceptual stages, rather than a dated release history. The shared foundation is live; adoption is integration by integration.
- Mutation 001
Separate gates
Mutation 001 / The local loginConceptual artwork The local login
Each product begins with its own answer.
Repeated account and session behaviour creates islands.
- Mutation 002
A central interchange
Mutation 002 / The shared accountConceptual artwork The shared account
One foundation becomes reusable.
Products can consume a shared identity service.
- Mutation 003
One constant nucleus
Mutation 003 / The principalConceptual artwork The principal
The person outlasts the credential.
HumanIdentity is independent of email and provider metadata.
- Mutation 004
A renewable bridge
Mutation 004 / The sessionConceptual artwork The session
Continuity becomes a responsibility.
Access can renew within its lifetime and end predictably.
- Mutation 005
One reusable module
Mutation 005 / The kitConceptual artwork The kit
Solve common client behaviour once.
IdentityKit shares persistence, validation, renewal and provider operations.
- Mutation 006
Independent destination gates
Mutation 006 / The entitlement bridgeConceptual artwork The entitlement bridge
Who you are and what you can use.
Identity supports product access without becoming the access rule.
- Mutation 007
A coherent ecosystem
Mutation 007 / The same humanConceptual artwork The same human
Different products. One durable answer.
The direction: shared recognition across integrated products, with explicit sessions and permissions.
GAMA Identity / Specimen 005 / Live & evolving
One person.
Many products.
One identity.
Identity should not be another thing
the person has to manage.