# Permissions Versioning Tool

## Overview

This custom build tool generates the `permission-versions.xml` file, which houses SDK versioning
metadata specifically for platform-defined permissions that require a purpose declaration.

The resulting XML file is bundled within the SDK zip package. Its primary function is to power
development tooling features, such as lint rules and auto-complete, associated with the Permissions
Purpose Declaration (PPD) feature. For more information about the tool and its implementation
details, please refer to go/pd-devx-eng.

## Sample Output

The current version of the tool relies on a naive implementation approach. It uses the
`requiresPurpose*TargetSdkVersion` attributes specified directly within the platform manifest as the
definitive source of truth for determining the minimum SDK versions at which these purpose
requirements were introduced.

Consider the following permission declared in the platform manifest:

```xml

<manifest xmlns:android='http://schemas.android.com/apk/res/android'>
    ...
    <permission android:name='android.permission.TEST' android:protectionLevel='normal'
        android:requiresPurposeStringTargetSdkVersion='38'
        android:requiresPurposeTargetSdkVersion='37' android:featureFlag='test.package.flag'>
        <valid-purpose android:name='purpose1' />
    </permission>
</manifest>
```

The XML artifact produced by the tool will contain the following permission block (assuming
'test.package.flag' is enabled for the build configuration):

```xml

<permissions>
    <permission name="android.permission.TEST" requiresPurposeStringMinTargetSdkVersion="38"
        requiresPurposeMinTargetSdkVersion="37">
        <valid-purpose name="purpose1" minSdkVersion="37" />
    </permission>
</permissions>
```

## Known Limitations

1. The current approach fails when an existing purpose-guarded permission is updated with additional
   valid purposes because the naive implementation utilizes the `requiresPurposeTargetSdkVersion`
   attribute to version all associated purposes uniformly.

2. Furthermore, if a purpose-guarded `<permission>` is removed from the platform manifest or
   converted to no longer require a purpose, the resulting XML artifact will lack the necessary
   historical versioning information. This omission will lead to incorrect validation outcomes for
   permission requests targeting older API levels.

These problems can be fixed by storing the snapshot of the artifact file
in [prebuilts/sdk](https://source.corp.google.com/h/googleplex-android/platform/superproject/main/+/main:prebuilts/sdk/)
and using the information from the last snapshot combined with the latest platform manifest metadata
to generate the artifact. More info can be
found [here](https://docs.google.com/document/d/1Kxm0WdejoSQRB9k9hWYDzsvJqm7E4VbeqmmHCkSdtYk/edit?tab=t.0#bookmark=id.c2ple3tcs7hb).
Tracking bug: b/454111429

Nevertheless, the current version of the tool remains valuable and sufficient until we encounter
the outlined use cases, which is not expected until the SDK release following the launch of the
PPD project.

## Testing

1. Ensure the transformation of `<permission>` blocks from the platform manifest are thoroughly
   unit tested. Currently, `atest SimplePermissionTransformerTest`

2. For E2E manual testing, you may invoke the java binary
   by [building](https://source.corp.google.com/h/googleplex-android/platform/superproject/main/+/main:development/build/README.md)
   the SDK directly. Please ensure ag/36482362 is patched locally before doing so. Unzip the SDK zip
   and find `permission-versions.xml` under the `data/` directory. This should also be the same
   place where you see the `api-versions-xml` file generated by Metalava.