Secret renovation proposal

[chrisli30]

After doing research on Vercel’s implementation, I propose the below changes to the Secret object

Single level access

Each Secret should be for only one level of access, it’s either at user, organization, or workflow level. The default is the user level. Each object should have three fields, but only 3 combinations: createdBy, {createdBy, workflowId}, {createdBy, orgId}.

createdBy: some_user_id,  
workflowId?: string | null,   
orgId?: string | null,

Priority

A unique identifier such as uuid or ulid should be used for Secret’s id, and Secret’s name allow duplicates. At runtime, when fetching a secret, Secretes are resolved based on priority.

1. If a workflow-level secret exists, it is used.
2. Otherwise, the default access, or the user-level secret is used.
3. If neither exists, the team-level secret is examined and used.

This avoids conflicts while allowing project-specific overrides. However, since the user could not retrieve and validate the value of secrets, the overriding behaviour would be very obscure and hard to trouble-shoot.

Create and Update Requests should return response

Instread of returning a boolean, a better approach is to return the created object, so the caller don’t retrieve and confirm the created object immediately without another query.

Therefore, the create or update response should be:

{
    "id": "an_ulid_id",
    "name": "some_name",
    "workflowId": string | null,   
    "orgId": string | null,         
    "createdBy": some_user_id,  
    "createdAt": "2025-02-12T12:34:56.789Z"
    "updatedAt": "2025-02-12T12:34:56.789Z"
  }

id - The reason we need an id is because name can change; there are cases user wants to rename a secret, but not change its value, so id is the most convenient unique identifier.
createdBy - The user identifier of the object, but createdBy makes more sense. Although the user id is derived from the authKey, the returned response should include this information.
createdAt and updatedAt - these are required to display the timestamps on UI.
value - value is only included in the request but not returned in the response, for security measures.

Delete reponse

In a Delete operation, only a few fields should be returned,

{
   "id": "sec_5e4e5f4e5f4e5f4e5f4e5f4e",
  "name": "name_of_secret",
  "deletedAt": "2025-02-12T12:45:00.789Z"
}

List response

Since List returns an array, we should use our standard interface, returning an object with pagination paramters.