fix(ai): send stable, non-sequential user identifiers to AI providers

[rasadregmi]

An operator-precedence bug in the AI providers' identifier expression — the ternary bound the app-uid suffix to the whole actor.user.id + actor.app?.uid sum instead of just the suffix — meant providers received user: ":undefined" (or a raw sequential id). All eight OpenAI-, Azure-, xAI-, Meta- and ZAI-style providers now build the identifier through one shared helper emitting puter-[-]. 212 provider-suite tests pass; typecheck and ESLint are clean.

Why

• The precedence bug meant no provider ever received the intended identifier, the shipped value was unusable (:undefined, or NaN on the numeric user_id paths).
• The intended value was also wrong: the sequential internal user id leaks signup order/count to AI vendors and is stable enough to correlate an account across apps and sessions.
• The OpenAI SDK types mark user deprecated in favor of safety_identifier (abuse detection) and prompt_cache_key (cache-hit bucketing); sending only user silently dropped the caching benefit.

What changed

• Shared helper - aiUserIdentifier(actor, maxLength) in src/backend/drivers/util/aiUserIdentifier.ts (src/backend/drivers/util/aiUserIdentifier.ts): puter-[-].
  • The random user UUID is always preserved in full; maxLength constrains only the app-bearing form; if there's no room for a distinguishing token the app suffix is omitted (never a dangling -, and never a collision-prone micro-truncation, token dropped below an 8-char budget).
  • App attribution reads effectiveApp, so access-token requests name the issuing app.
  • Nothing is sent for the system actor; Meta/ZAI keep caller-supplied safety_identifier/user_id overrides.
  • Cap comment cites verified sources only: OpenAI 64 (SDK types), Z.AI 6-128 (docs); Meta/xAI document none.
• prompt_cache_key - the four OpenAI/Azure chat providers and Meta now send it alongside safety_identifier, defaulting to the same per-user identifier unless the caller supplies one; Azure's Grok branch drops both fields (it 400s on unknown args).
• xAI image edit - #edit forwards user like generation and takes named options so user can't transpose with aspectRatio.

Testing

• Shared four-actor matrix (user / user+app / access token / system) with assertActorMatrixIdentifiers() across the six OpenAI-style suites (image suites assert user; chat suites also check the aliased fields).
• Helper suite: exact strings, size caps (36-char UUID + 40-char app UID at 64 → app token to exactly 21 chars, UUID intact), zero-budget, sub-base maxLength on both branches, collision-guard threshold, system/missing-UUID cases.
• Azure Grok test runs under a real user actor and verifies safety_identifier/prompt_cache_key are stripped; xAI/OpenAI edit-path identifier tests; caller-supplied prompt_cache_key override test.

Verification

• 9 affected suites, 212 tests passing.
• npm run typecheck: no new errors.
• ESLint clean on touched files (5 pre-existing unrelated warnings).
• test:backend full runs green; two one-off flakes (Postgres migration-integration timeout, a MetaProvider test) were environmental and did not reproduce — none in the identifier path.

[CLAassistant]

All committers have signed the CLA.

[ProgrammerIn-wonderland]

@404oops can you review?

[404oops]

I don't think this is ready to merge. The fix creates several new problems, mostly because it reuses the same flawed pattern in multiple places instead of centralizing how the safety identifier is built.

When a request is authenticated with an access token instead of a direct user session, the actor record does not put the issuing app in actor.app, but in actor.effectiveApp.

The current code reads actor.app?.uid, so for access-token requests, the provider still gets the user ID, but no app ID. This means you can't tell whether abuse is coming from a third-party app, or from the user directly.

It also leaks our internal sequential user IDs to external AI vendors. That lets them correlate Puter users across different services, and estimate rough signup order and total user count.

This is especially bad, because the old code accidentally avoided sending the raw ID at all due to a precedence bug. Azure and OpenAI previously sent :undefined; the others sent an empty string because numeric ID plus undefined became NaN.

With this PR, OpenAI, Azure, and xAI start sending the raw integer for the first time. Meta and ZAI already receive it as puter-<id>. We should send a UUID or a hash instead, but that should be up to us to decide.

The PR description says it mirrors MetaProvider, but that's inaccurate. MetaProvider and ZAIProvider have the same actor.app?.uid bug and the same raw integer problem, so copying them just spreads it across 8 places, instead of fixing it.

Also, Meta and ZAI use the format puter-<id>-<appUid>, while this code uses <id>:<appUid>. This should've been one shared helper that reads actor.effectiveApp ?? actor.app and returns a non-sequential identifier.

The ?? actor.app fallback is safe because makeActor derives effectiveApp from app, so a null effectiveApp always means app is null too. The fallback is only needed because the new tests construct actor objects directly without using makeActor, leaving effectiveApp undefined. Either keep the fallback or update the tests to use makeActor and only read actor.effectiveApp.

Test gaps

• The existing Azure test titled "sends safety_identifier for OpenAI deployments" now runs under the system actor. With the new code, both relevant fields are undefined, and the assertion passes only because { safety_identifier: undefined } still creates an undefined value. The test title no longer matches what it actually verifies. It should either run under a user actor or be renamed to assert that the value is undefined. The same applies to the safety_identifier assertion at the end of the Azure Responses request-shape test, which assigns undefined directly and likewise passes for the wrong reason.

• The two Azure tests and the two image tests do not include a system-actor case, but the OpenAI chat tests do.

• There is no access-token test anywhere. Adding one that expects 42:app-abc would fail against the current code.

• The Grok "strip safety_identifier" test is still valid, because the identifier is removed before the request goes out.

To be clear, the precedence fix itself is correct, and the actor?.user?.id chaining removes the old TypeError. That part is fine. But the rest of the change is a quick fix that introduces bigger problems than it solves.

[rasadregmi]

@404oops
Thanks for the thorough review, I've reworked the change along those lines.

One shared helper. All eight providers now build their identifier via src/backend/drivers/util/aiUserIdentifier.ts, and Meta/ZAI use it too:

export const aiUserIdentifier = (actor, maxLength = 64) => {
if (!actor || isSystemActor(actor)) return undefined;
const userUuid = actor.user?.uuid;
if (!userUuid) return undefined;
const appUid = actor.effectiveApp?.uid ?? actor.app?.uid;
const identifier = appUid ? puter-${userUuid}-${appUid} : puter-${userUuid};
return identifier.slice(0, maxLength);
};

• Reads effectiveApp ?? app, so access-token requests name the issuing app (your makeActor note is exactly why the fallback is safe to keep).
• Sends the user's random UUID, never the sequential id, no raw integer leaks, and the old :undefined/NaN noise is gone entirely.
• Returns undefined for the system actor and when there's no UUID.
• Dash separators, matching the existing puter-<...>- format Meta/ZAI already used.
• Same caps as before: 64 everywhere, ZAI keeps 128. Meta/ZAI still honor a caller-supplied safety_identifier/user_id override.

Test updates.

• Access-token cases added to every provider suite, a token issued by an app now sends puter-u42-app-abc via effectiveApp, which fails against the old actor.app-only read.
• System-actor cases added to the Azure chat, Azure responses, and both image suites (asserted undefined).
• Vacuous Azure assertions fixed: sends safety_identifier for OpenAI deployments and the Azure Responses check now run under a real user actor instead of passing on { safety_identifier: undefined }.

Verification. Nine affected suites pass (203 tests); npm run typecheck has no new errors. Full npm run test:backend is green for everything touched by this change, the only intermittent failures are pre-existing env-dependent ones (PostgresDatabaseClient.integration 180s timeouts and the share-email suite: they pass in isolation and flake run-to-run regardless of this diff, and this run had a different subset fail than the last).

[404oops]

I have more notes on this.

1. src/backend/drivers/util/aiUserIdentifier.ts at line 48: The identifier this produces for a real user and a real app does not survive the cap on this line intact. The tests do not catch it.

2. src/backend/drivers/ai-image/providers/xai/XAIImageProvider.ts at line 183: The edit path does not do what the generation path at line 130 does.

3. src/backend/drivers/ai-chat/providers/azure/AzureChatProvider.test.ts at line 468: This test would still pass if user were removed from the Grok branch it covers.

4. OpenAiChatCompletionsProvider.ts at line 184 and AzureChatProvider.ts at line 211: Switching user from per-app to per-user has a side effect on OpenAI's end that the PR does not address or mention.

5. aiUserIdentifier.ts at lines from 23 to 39: The exported constant, its comment, and the maxLength parameter do not hold up when checked against their callers and against the OpenAI SDK docs.

6. aiUserIdentifier.ts at line 44: The fallback on this line is not reachable by any actor the codebase actually builds, and the test that covers it shows why.

7. ZAIProvider.test.ts at line 409: Comment is stale.

8. The commit subject contradicts the commit body.

9. OpenAiImageProvider.test.ts at line 254 is in the wrong describe block.

10. The four-actor test matrix is pasted into six files.

Please, take a look at the code, attack it from all sides and try to do extensive reviews. I think your agent did a shallow analysis, which lead to these problems and holes.

I'm not saying this PR is bad at all, this is a good PR, but some things are simply overlooked and that's a BIG issue when you're attempting to fix a problem.

Do fix those issues, and if you (or your agent) find more within the scope of what you were trying to solve, don't hesitate to fix them as well.

[rasadregmi]

I have more notes on this.

1. src/backend/drivers/util/aiUserIdentifier.ts at line 48: The identifier this produces for a real user and a real app does not survive the cap on this line intact. The tests do not catch it.
2. src/backend/drivers/ai-image/providers/xai/XAIImageProvider.ts at line 183: The edit path does not do what the generation path at line 130 does.
3. src/backend/drivers/ai-chat/providers/azure/AzureChatProvider.test.ts at line 468: This test would still pass if user were removed from the Grok branch it covers.
4. OpenAiChatCompletionsProvider.ts at line 184 and AzureChatProvider.ts at line 211: Switching user from per-app to per-user has a side effect on OpenAI's end that the PR does not address or mention.
5. aiUserIdentifier.ts at lines from 23 to 39: The exported constant, its comment, and the maxLength parameter do not hold up when checked against their callers and against the OpenAI SDK docs.
6. aiUserIdentifier.ts at line 44: The fallback on this line is not reachable by any actor the codebase actually builds, and the test that covers it shows why.
7. ZAIProvider.test.ts at line 409: Comment is stale.
8. The commit subject contradicts the commit body.
9. OpenAiImageProvider.test.ts at line 254 is in the wrong describe block.
10. The four-actor test matrix is pasted into six files.

Please, take a look at the code, attack it from all sides and try to do extensive reviews. I think your agent did a shallow analysis, which lead to these problems and holes.

I'm not saying this PR is bad at all, this is a good PR, but some things are simply overlooked and that's a BIG issue when you're attempting to fix a problem.

Do fix those issues, and if you (or your agent) find more within the scope of what you were trying to solve, don't hesitate to fix them as well.

Thanks for the second pass. This revision is squashed to a single commit and addresses every point:

1. Cap truncating the identifier. Fixed. aiUserIdentifier preserves the full user UUID; only the app-bearing form is constrained. The app token is truncated to fit the budget and omitted entirely when the remaining budget is below 8 chars — where a truncation could collide with another app's uid. The user-only form is always returned in full, never sliced. New tests: realistic 36-char UUID + 40-char app- at a 64 cap (app token to exactly 21 chars, UUID intact), zero-budget, sub-base maxLength on both branches, and the collision-guard threshold.
2. xAI edit path. #edit now forwards user like generation and takes a named-options parameter, so user can't be silently transposed with the adjacent same-typed aspectRatio in a future edit.
3. Vacuous Grok test. Now runs under a user actor and asserts user present while safety_identifier/prompt_cache_key are absent; removing either from the Grok branch fails the test.
4. Per-user visibility on OpenAI's end. Agreed this goes beyond the precedence fix: the OpenAI SDK types mark user deprecated, directing callers to safety_identifier (abuse detection) and prompt_cache_key (cache-hit bucketing). The four OpenAI/Azure chat providers and Meta now send prompt_cache_key too, defaulted to the same per-user identifier unless the caller supplies one. OpenAI observes a stable UUID-based identifier — never the sequential id — where the bug produced :undefined/NaN; user is retained for request-shape compatibility.
5. Constant/comment/maxLength vs docs. The cap comment cites only verified limits: 64 for safety_identifier (from the OpenAI SDK types for both APIs) and 6-128 for ZAI user_id (Z.AI docs). Meta and xAI document no limit, so none is claimed. The JSDoc states that maxLength constrains the app-bearing form only.
6. Unreachable fallback. ?? actor.app?.uid removed; the helper reads only effectiveApp, and the test matrix constructs actors through makeActor, exercising the real production path.
7. ZAI stale comment. Fixed: SYSTEM_ACTOR is excluded via isSystemActor(), not an absent uuid.
8. Commit subject. Now fix(ai): send stable, non-sequential user identifiers to AI providers, agreeing with the body (squashed to one commit).
9. Misplaced image test. Moved out of output-extraction into its own user-identifier describe, with edit-path coverage.
10. Duplicated matrix. makeActorMatrix() and assertActorMatrixIdentifiers() shared across the six OpenAI-style suites; Meta/ZAI keep their provider-specific cases.
11. Depth of review. Accepted. The follow-up sweep exposed the truncation, the collision-guard hole, the vacuous assertions, the dead fallback, and the edit-path/misplacement issues on top of the original precedence bug.

Verification: 212 provider-suite tests pass; npm run typecheck has no new errors; ESLint clean on all touched files (the 5 pre-existing no-explicit-any warnings in OpenAiChatResponsesProvider.ts are unrelated and untouched).