Identity
Identity
Purpose. Defines who an operation belongs to: the tenant (scope), the app binding it was created for, the typed destination it targets, and the pool and cache boundaries that follow from those. Sources: docs/PLAN.md §4.2 and §6.1, and src/Core/Identity, src/Core/Transport/ConnectionProfile.php.
Rules
- Scope is a tenant boundary. It is a string, defaults to
default, and comes fromMobilePush::scopeUsing()or->scope(). It is never taken from client payload (plan §4.2). Scope::normalize()trims the value; an empty value becomesdefault; anything else must match[A-Za-z0-9._:-]with at most 64 characters, otherwise it throws\InvalidArgumentException(note: not aPushException).- App binding:
BindingRef { scope, name, provider, appId, environment, generation }. The generation changes on every credential rotation or reconfiguration (plan §4.2, code comment). - A job carries a
BindingRef(and the destination reference and generation), never the secret. At consume time the current credential is resolved for that identity. If it does not match, the result isSkippedwithReasonCode::BindingMismatchand no fallback to the default connection (plan §4.2). A generation change alone is not a mismatch: the current credential of the same identity is used. A mismatch is a different identity (scope, provider, app id or environment) behind the same name, or an identity that no longer resolves (orchestrator’s resolution,README.md). Directsend()also dispatchesSending\Events\BindingMismatchDetected; the durable relay and the light job handle it in their own way (docs/delivery-profiles.md). - Destinations are typed. Provider, token type, bundle and environment are never inferred from the shape of a string. Each destination is built with
::of($value), which normalizes and validates and throwsInvalidDestinationException(aValidationException) before any network call. - Destinations are disjoint classes; a value of one type cannot be passed as another.
ConnectionProfile::$poolKeyis an opaque string. Requests with different pool keys never share a connection.Core\Driver\PoolKeybuilds it from the provider, endpoint role, host and port, the effective credential identity (APNs token: team id and key id; mTLS: SHA-256 certificate fingerprint; FCM: the Google principal), environment, HTTP version, proxy (only hashed: it may hold a password), CA bundle, credential generation and binding generation. The scope is deliberately not an input: two tenants that share one credential may share a connection; two different credentials never do.- The scope applies to caches, locks, deduplication, receipts,
export/forget, devices, Live Activities, campaigns and channel actions (plan §4.2); every ledger and registry query is scoped.
Scope, binding and generation
| Field | Source of the value | Notes |
|---|---|---|
scope |
scopeUsing() / ->scope() |
Default default |
name |
connection name in host config | Not part of identity() |
provider |
Provider::Apns or Provider::Fcm |
|
appId |
APNs: bundle ID. FCM: Firebase project ID | Plan §4.2 also says “+ package” for FCM; the code has no package field (see Plan vs code) |
environment |
Environment::Production or Sandbox |
FCM is always Production per the enum’s docblock |
generation |
string, default '1' |
Bumped on every rotation |
identity(): SHA-256 over scope, provider, appId and environment. Generation and name are excluded. Use it to scope caches, limits and ledger rows.fingerprint():identity()plus name and generation.sameIdentityAs(),toArray()andfromArray()serialize the binding for jobs; the array holds no secret.
Typed destinations
Class (Identity\Destination\) |
DestinationKind |
Accepted value (from code) |
|---|---|---|
ApnsDeviceToken |
apns_device_token |
Hex, lowercased, even length, at least 64 characters |
ApnsVoipToken |
apns_voip_token |
Same hex rule (PushKit token) |
ApnsLiveActivityToken |
apns_live_activity_token |
Same hex rule |
ApnsPushToStartToken |
apns_push_to_start_token |
Same hex rule |
ApnsBroadcastChannel |
apns_broadcast_channel |
Base64-style characters, 8 to 256 long |
FcmToken |
fcm_token |
Non-empty, at most 4096 characters, no whitespace |
FcmFid |
fcm_fid |
Exactly 22 characters from [A-Za-z0-9_-] |
FcmTopic |
fcm_topic |
Leading /topics/ removed; [a-zA-Z0-9-_.~%], 1 to 900 characters |
FcmCondition |
fcm_condition |
Non-empty, at most 2048 characters, contains in topics |
- All destinations share
AbstractDestination: private constructor,of(),value(),ref(),withRef()(returns a copy),equals()(same kind and same value, compared withhash_equals). __debugInfo()redacts the value:[redacted <kind>].DestinationKind::isIndividual()is false for broadcast channels, topics and conditions. No receipt, cap, fallback or invalidation applies to them (plan §8 is consistent with this).
Types
Identity\Scope,BindingRef,Provider,Environment,Platform(ios,android)Identity\Destination(interface),DestinationKind,DestinationRef { id, generation (int), ownerType, ownerId }Identity\Destination\*(table above) andAbstractDestinationTransport\ConnectionProfile(carriespoolKey)
Worked cases
A. Token with the same value in two tenants.
- Situation: tenant
acmeand tenantbetaboth register the same APNs device token string. - The package: two
BindingRefs have differentidentity()values; caches, limits and ledger rows are separate because they are scoped. - The caller sees: each send is resolved against its own scope; neither tenant’s result changes the other’s.
B. Malformed token.
- Situation:
ApnsDeviceToken::of('abc'). - The package: validation fails before any network call.
- The caller sees:
InvalidDestinationException. No provider is guessed from the string.
C. Topic with prefix.
- Situation:
FcmTopic::of('/topics/news'). - The package: normalizes to
news. - The caller sees:
value() === 'news'.
D. Job after credential rotation.
- Situation: a job was queued for generation 7; the credential is now generation 8.
- The package: the identity is the same, so the current credential (generation 8) is used. Only a different identity (for example the connection now points to another bundle id) is a mismatch.
- The caller sees: the normal result of the send; for a mismatch,
SkippedwithBindingMismatch.
Plan vs code
- Plan §4.2 lists eight destination classes. The code has nine: it adds
ApnsVoipTokenon purpose (a PushKit token is a different registration from a device token). Plan §6.3 mentions VoIP payload limits, so VoIP is in scope. - Plan §4.2 says FCM
app_idis “project + package”.BindingRefonly hasappId(the Firebase project id); the Android package restriction is a message option (restricted_package_name), not part of the identity (orchestrator’s resolution). - Plan §4.2 says
Scopevalues come fromMobilePush::scopeUsing(). That is the Laravel layer, not insrc/Core. FcmConditionvalidation only checks for the substringin topics: a syntax sanity check on an explicitly typed value, not inference and not a parse of the expression. Google validates it.BindingRef::$generationis a string, whileDestinationRef::$generationis an int. The plan does not specify either type.
Open points
- Whether the FCM
environmentis alwaysProduction(code docblock) or may be declared by the app (plan §4.2 applies that rule to devices generally). The code always usesProductionfor FCM; nothing in the package needs another value.
This page is generated from docs/contracts/identity.md. To change it, edit that file in the repository, not this site.