feat: add new functions based on session ADR 0030

[porcellus]

Summary of change

(A few sentences about this PR)

Related issues

• https://supertokens.com/docs/contribute/decisions/session/0030

Test Plan

TODO

Documentation changes

TODO

Checklist for important updates

• Changelog has been updated
• coreDriverInterfaceSupported.json file has been updated (if needed)
  • Along with the associated array in lib/ts/version.ts
• frontendDriverInterfaceSupported.json file has been updated (if needed)
• Changes to the version if needed
  • In package.json
  • In package-lock.json
  • In lib/ts/version.ts
• Had run npm run build-pretty
• Had installed and ran the pre-commit hook
• Issue this PR against the latest non released version branch.
  • To know which one it is, run find the latest released tag (git tag) in the format vX.Y.Z, and then find the latest branch (git branch --all) whose X.Y is greater than the latest released tag.
  • If no such branch exists, then create one from the latest released branch.
• If have added a new web framework, update the add-ts-no-check.js file to include that
• If added a new recipe / api interface, then make sure that the implementation of it uses NON arrow functions only (like someFunc: function () {..}).
• If added a new recipe, then make sure to expose it inside the recipe folder present in the root of this repo. We also need to expose its types.

Remaining TODOs for this PR

• Tests
• Base PR merge

[rishabhpoddar]

Suggested change

	getTokensDangerously(): {
	getAllSessionTokensDangerously(): {

[rishabhpoddar]

Suggested change

	if (res.status === "OK" && res.session !== undefined) {
	if (res.status === "OK") {

[rishabhpoddar]

For the getSessionWithoutModifyingResponse function, if it return an invalid claim error, the err object from that response can directly be sent to the frontend as a JSON serialisable with 403? Or does something else need to be done

[rishabhpoddar]

can you share code snippet here of how to actually use getSessionWithoutModifyingResponse and handle all the errors + success state from it?

[rishabhpoddar]

related to dynamic vs static keys, we decided to remove the useDynamicKey arg from createNewSession (so just on a global level), and to check for the kid in the JWT post session verification based on the value of the global variable (do this check if the token is >= v3). Note that if the kid is a UUID only, then we treat it as a static key.

If the setting vs the kid format doesn't match, then we throw try refresh token error.

[rishabhpoddar]

• we need to create just one recipe function for createNewSession which doesn't take a req / res (but the request will be passed to it via userContext)
• The createNewSession(req, res, ..) will also call this function, and set the userContext correctly.
• The createNewSessionWithoutReqeustResponse will also call this same function, but will not have req in userContext

[rishabhpoddar]

Can we call it "UNAUTHORISED"

[rishabhpoddar]

Let's evaluate this based on the snippet you provide: Snippet should compare how to use this function vs using getSession function

[porcellus]

async function getSessionWithoutRequestOrErrorHandler(
    req: express.Request,
    resp: express.Response,
) {
    const accessToken = req.headers.authorization?.replace(/^Bearer /, "");

    // We only need to split this declaration (and have the else statement) if the session is optional
    let session;
    if (!accessToken) {
        // This means that the user doesn't have an active session
        return resp.status(401).json({ message: "try again " }); // Or equivalent...
    } else {
        const result = await Session.getSessionWithoutRequestResponse(accessToken, undefined, { antiCsrfCheck: false });

        // Note that the return type forces the user to have (or at least notice) error handling
        if (result.status === "CLAIM_VALIDATION_ERROR") {
            return resp.status(403).json(result); // Or equivalent...
        } else if (result.status !== "OK") {
            // We could need separate handling here if we expect non-ST access tokens
            return resp.status(401); // Or equivalent...
        }
        session = result.session;
    }
    // API code...
    
    if (session) {
        const tokens = session.getAllSessionTokensDangerously();
        if (tokens.accessAndFrontTokenUpdated) {
            resp.set("st-access-token", tokens.accessToken);
            resp.set("front-token", tokens.frontToken);
        }
    }
}

async function getSessionWithoutRequestWithErrorHandler(
    req: express.Request,
    resp: express.Response,
) {
    const accessToken = req.headers.authorization?.replace(/^Bearer /, "");

    // We only need to split this declaration (and have the else statement) if the session is optional
    let session;
    if (!accessToken) {
        // This means that the user doesn't have an active session
        return resp.status(401).json({ message: "try again " });
    } else {
        const result = await Session.getSessionWithoutRequestResponse(accessToken, undefined, { antiCsrfCheck: false });

        // Note that the return type forces the user to have (or at least notice) error handling
        if (result.status === "CLAIM_VALIDATION_ERROR") {
            throw new Session.Error({
                type: "INVALID_CLAIMS",
                payload: result.claimValidationErrors,
                message: "INVALID_CLAIMS",
            });
        } else if (result.status !== "OK") {
            // We could need separate handling here if we expect non-ST access tokens
            throw result.error;
        }
        session = result.session;
    }
    // API code...
    if (session) {
        const tokens = session.getAllSessionTokensDangerously();
        if (tokens.accessAndFrontTokenUpdated) {
            resp.set("st-access-token", tokens.accessToken);
            resp.set("front-token", tokens.frontToken);
        }
    }
}

[rishabhpoddar]

• check that this all actually works
• we decided to introduce result.response for invalid claim error, which matches the fdi json being sent. And also keep result.error in case we want to throw.
• Add: How to use createNewSessionWithoutRequestResponse and how to use refreshSessionWithoutRequestResponse

[porcellus]

async function createNewSessionWithoutRequestResponse(req: express.Request, resp: express.Response) {
    const userId = "user-id"; // This would be fetched from somewhere

    const result = await Session.createNewSessionWithoutRequestResponse(userId);

    const tokens = result.session.getAllSessionTokensDangerously();
    if (tokens.accessAndFrontTokenUpdated) {
        resp.set("st-access-token", tokens.accessToken);
        resp.set("front-token", tokens.frontToken);
        resp.set("st-refresh-token", tokens.refreshToken);
        if (tokens.antiCsrfToken) {
            resp.set("anti-csrf", tokens.antiCsrfToken);
        }
    }
}

async function refreshSessionWithoutRequestResponse(req: express.Request, resp: express.Response) {
    const refreshToken = req.headers.authorization?.replace(/^Bearer /, "");

    if (!refreshToken) {
        // This means that the user doesn't have an active session
        return resp.status(401);
    } else {
        const result = await Session.refreshSessionWithoutRequestResponse(refreshToken, true);
        if (result.status !== "OK") {
            return resp
                .status(401)
                .set("st-access-token", "")
                .set("set-refresh-token", "")
                .set("front-token", "remove"); // Or equivalent...
        }
        const tokens = result.session.getAllSessionTokensDangerously();
        if (tokens.accessAndFrontTokenUpdated) {
            resp.set("st-access-token", tokens.accessToken);
            resp.set("front-token", tokens.frontToken);
            resp.set("st-refresh-token", tokens.refreshToken);
            if (tokens.antiCsrfToken) {
                resp.set("anti-csrf", tokens.antiCsrfToken);
            }
        }
    }
}

[rishabhpoddar]

omit sessionRequired from VerifySessionOptions

[rishabhpoddar]

we should add an err to all of the non-ok status types + remove clearTokens

[rishabhpoddar]

wrong message

[rishabhpoddar]

why asdf?

[rishabhpoddar]

add a comment about anticsrf checks (and failure returns TRY_REFRESH_TOKEN_ERROR):

• if anti-csrf value in access token and input antiCsrfToken don't match
• if we are supposed to do anti-csrf check (based on the options and the anti-csrf setting in the config), and input antiCsrfToken is undefined. This implies that if someone is using header based auth, they should set the options to have antiCsrf check as false.

[rishabhpoddar]

Suggested change

	/*
	In all cases: if sIdRefreshToken token exists (so it's a legacy session) we clear it.
	Check http://localhost:3002/docs/contribute/decisions/session/0008 for further details and a table of expected behaviours
	*/

[rishabhpoddar]

Suggested change

	setRequestInUserContextIfNotDefined(userContext, req);
	userContext = setRequestInUserContextIfNotDefined(userContext, req);